Deploy Documentation #131
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: Deploy Documentation | |
| on: | |
| push: | |
| branches: | |
| - main | |
| paths: | |
| - 'docs/**' | |
| - 'mkdocs.yml' | |
| - '.github/workflows/deploy-docs.yml' | |
| # Redeploy after a successful release so the Quick Start version (injected | |
| # below from the latest git tag) tracks the newest release automatically. | |
| # Using workflow_run (not a gh workflow_dispatch from the CI job) because a | |
| # workflow_dispatch triggered by GITHUB_TOKEN is suppressed by GitHub's | |
| # recursion guard and would never fire. | |
| workflow_run: | |
| workflows: ["ci"] | |
| types: | |
| - completed | |
| workflow_dispatch: | |
| # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages | |
| permissions: | |
| contents: read | |
| pages: write | |
| id-token: write | |
| # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. | |
| # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. | |
| concurrency: | |
| group: "pages" | |
| cancel-in-progress: false | |
| jobs: | |
| deploy: | |
| name: Deploy to GitHub Pages | |
| runs-on: ubuntu-latest | |
| # For workflow_run, only deploy after a SUCCESSFUL release CI run (a tag | |
| # push — head_branch is the tag name, e.g. "v1.29.0"). This keeps regular | |
| # main-branch commits from redeploying via this path (the push trigger | |
| # above already handles docs/** changes). | |
| if: >- | |
| github.event_name != 'workflow_run' || | |
| (github.event.workflow_run.conclusion == 'success' && | |
| startsWith(github.event.workflow_run.head_branch, 'v')) | |
| environment: | |
| name: github-pages | |
| url: ${{ steps.deployment.outputs.page_url }} | |
| steps: | |
| - name: Checkout repository | |
| uses: actions/checkout@v6 | |
| with: | |
| fetch-depth: 0 | |
| - name: Setup Pages | |
| uses: actions/configure-pages@v6 | |
| - name: Setup Python | |
| uses: actions/setup-python@v6 | |
| with: | |
| python-version: '3.12' | |
| - name: Install MkDocs Material | |
| run: pip install 'mkdocs-material>=9,<10' | |
| # Rewrite the Quick Start example version to the latest release tag at | |
| # publish time (not committed), so the live docs always match the newest | |
| # release without pushing to the protected main branch. | |
| - name: Sync Quick Start version to latest release | |
| run: ./scripts/update_docs_version.sh | |
| - name: Build site | |
| run: mkdocs build --strict | |
| # Publish the raw Markdown sources alongside the rendered HTML so AI | |
| # crawlers (which prefer Markdown and don't execute JS) can read pages | |
| # directly — docs/llms.txt indexes these URLs. | |
| - name: Publish raw Markdown for AI crawlers | |
| run: | | |
| find docs -maxdepth 1 -name '*.md' \ | |
| ! -name 'VIEW_DOCS_LOCALLY.md' \ | |
| ! -name 'websocket-migration-plan.md' \ | |
| -exec cp {} site/ \; | |
| touch site/.nojekyll | |
| - name: Verify site structure | |
| run: | | |
| test -f site/index.html | |
| test -f site/CNAME | |
| test -f site/sitemap.xml | |
| test -f site/llms.txt | |
| test -f site/quickstart/index.html | |
| echo "✓ site structure OK" | |
| - name: Upload artifact | |
| uses: actions/upload-pages-artifact@v5 | |
| with: | |
| path: 'site' | |
| - name: Deploy to GitHub Pages | |
| id: deployment | |
| uses: actions/deploy-pages@v5 | |
| - name: Output deployment URL | |
| run: | | |
| echo "Documentation deployed successfully!" | |
| echo "URL: ${{ steps.deployment.outputs.page_url }}" |