chore: sync documentation and reader runtime updates #9
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: Docs GitHub Pages Publish | |
| on: | |
| push: | |
| branches: | |
| - main | |
| - master | |
| paths: | |
| - "docs/**" | |
| - "mkdocs.yml" | |
| - "docs/requirements-mkdocs.txt" | |
| - "scripts/run-mkdocs.js" | |
| - "package.json" | |
| - "package-lock.json" | |
| - "README.md" | |
| - ".github/workflows/docs-github-pages-publish.yml" | |
| workflow_dispatch: | |
| inputs: | |
| git_ref: | |
| description: "Branch, tag, or commit to publish from (rollback)" | |
| required: false | |
| type: string | |
| site_url: | |
| description: "MkDocs site_url override" | |
| required: false | |
| default: "https://jacobinwwey.github.io/NoteConnection/" | |
| type: string | |
| base_path: | |
| description: "MkDocs base path override" | |
| required: false | |
| default: "/NoteConnection/" | |
| type: string | |
| permissions: | |
| contents: write | |
| concurrency: | |
| group: docs-github-pages | |
| cancel-in-progress: false | |
| env: | |
| FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true" | |
| jobs: | |
| verify-diataxis-map: | |
| name: verify-diataxis-map | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout repository | |
| uses: actions/checkout@v5 | |
| with: | |
| ref: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.git_ref != '' && github.event.inputs.git_ref || github.ref }} | |
| lfs: false | |
| - name: Setup Node.js | |
| uses: actions/setup-node@v5 | |
| with: | |
| node-version: "20" | |
| cache: "npm" | |
| - name: Install dependencies | |
| run: npm ci | |
| - name: Verify Diataxis mapping governance | |
| run: npm run docs:diataxis:check | |
| build-site: | |
| name: build-site | |
| runs-on: ubuntu-latest | |
| needs: verify-diataxis-map | |
| steps: | |
| - name: Checkout repository | |
| uses: actions/checkout@v5 | |
| with: | |
| ref: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.git_ref != '' && github.event.inputs.git_ref || github.ref }} | |
| lfs: false | |
| - name: Setup Python | |
| uses: actions/setup-python@v6 | |
| with: | |
| python-version: "3.12" | |
| cache: "pip" | |
| cache-dependency-path: docs/requirements-mkdocs.txt | |
| - name: Install MkDocs dependencies | |
| run: pip install -r docs/requirements-mkdocs.txt | |
| - name: Resolve MkDocs runtime URL config | |
| shell: bash | |
| run: | | |
| SITE_URL="${{ github.event_name == 'workflow_dispatch' && github.event.inputs.site_url || '' }}" | |
| BASE_PATH="${{ github.event_name == 'workflow_dispatch' && github.event.inputs.base_path || '' }}" | |
| if [ -z "${SITE_URL}" ]; then | |
| SITE_URL="https://jacobinwwey.github.io/NoteConnection/" | |
| fi | |
| if [ -z "${BASE_PATH}" ]; then | |
| BASE_PATH="/NoteConnection/" | |
| fi | |
| echo "MKDOCS_SITE_URL=${SITE_URL}" >> "$GITHUB_ENV" | |
| echo "MKDOCS_BASE_PATH=${BASE_PATH}" >> "$GITHUB_ENV" | |
| echo "MKDOCS_DOCS_HOST=https://jacobinwwey.github.io/" >> "$GITHUB_ENV" | |
| echo "site_url=${SITE_URL}" >> "$GITHUB_OUTPUT" | |
| echo "base_path=${BASE_PATH}" >> "$GITHUB_OUTPUT" | |
| - name: Build docs site | |
| run: mkdocs build --config-file mkdocs.yml | |
| - name: Preflight GitHub Pages enablement check | |
| shell: bash | |
| env: | |
| GITHUB_TOKEN: ${{ github.token }} | |
| run: | | |
| PAGES_API="https://api.github.com/repos/${{ github.repository }}/pages" | |
| STATUS_CODE="$(curl -sS -o /tmp/pages-site.json -w '%{http_code}' \ | |
| -H 'Accept: application/vnd.github+json' \ | |
| -H "Authorization: Bearer ${GITHUB_TOKEN}" \ | |
| "${PAGES_API}")" | |
| if [ "${STATUS_CODE}" = "404" ]; then | |
| echo "::warning::GitHub Pages site is not enabled yet for this repository. CI can still publish gh-pages branch, but https://jacobinwwey.github.io/NoteConnection/ will stay 404 until Settings -> Pages is configured to Deploy from branch (gh-pages / root)." | |
| elif [ "${STATUS_CODE}" -ge 200 ] && [ "${STATUS_CODE}" -lt 300 ]; then | |
| echo "GitHub Pages site API is available (HTTP ${STATUS_CODE})." | |
| else | |
| echo "::warning::Unable to verify GitHub Pages site state (HTTP ${STATUS_CODE})." | |
| fi | |
| - name: Deploy docs to gh-pages branch | |
| uses: peaceiris/actions-gh-pages@v4 | |
| with: | |
| github_token: ${{ secrets.GITHUB_TOKEN }} | |
| publish_dir: build/mkdocs-site | |
| publish_branch: gh-pages | |
| force_orphan: true | |
| commit_message: "docs: publish site from ${{ github.sha }}" |