Skip to content
docs

docs: add MkDocs Material site deployed to GitHub Page #1

Sign in to view logs

docs: add MkDocs Material site deployed to GitHub Page

docs: add MkDocs Material site deployed to GitHub Page #1

Workflow file for this run

.github/workflows/docs.yml at 07ea916
---
name: docs
# Build and deploy the MkDocs site to GitHub Pages.
# * pull_request — build only (validates the docs render
# without publishing).
# * push to main — build + deploy to gh-pages.
# * workflow_dispatch — same as push (lets operators
# re-publish without a docs change).
on:
pull_request:
paths:
- "docs/**"
- "mkdocs.yml"
- "CHANGELOG.md"
- "cmd/hypercache-server/README.md"
- ".github/workflows/docs.yml"
push:
branches: [main]
paths:
- "docs/**"
- "mkdocs.yml"
- "CHANGELOG.md"
- "cmd/hypercache-server/README.md"
- ".github/workflows/docs.yml"
workflow_dispatch:
# Pages deployments require these permissions; the build-only
# branch (PR) doesn't actually use the deploy steps so the
# extra permissions are harmless.
permissions:
contents: read
pages: write
id-token: write
# A single in-flight deploy at a time. Newer pushes cancel
# older ones to avoid an out-of-order publish.
concurrency:
group: pages
cancel-in-progress: true
jobs:
build:
name: build
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: actions/checkout@v6
with:
fetch-depth: 0 # docs/ may reference files via relative paths
- name: Setup Python
uses: actions/setup-python@v6
with:
python-version: "3.13"
cache: pip
- name: Install MkDocs + plugins
run: |
python -m pip install --upgrade pip
pip install mkdocs-material \
mkdocs-include-markdown-plugin \
mkdocs-glightbox
- name: Build site (strict)
# Strict in CI catches broken links / missing pages on PR;
# `mkdocs serve` locally relaxes this for fast iteration.
run: mkdocs build --strict
- name: Upload Pages artifact
if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
uses: actions/upload-pages-artifact@v3
with:
path: ./site
deploy:
name: deploy
needs: build
if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
runs-on: ubuntu-latest
timeout-minutes: 5
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4