beads/.github/workflows/deploy-docs.yml
matt wilkie 87e698ad90
ci(docs): add --fallback-extensions html to lychee link check (#3736)
Docusaurus is configured with `trailingSlash: false`, which emits
`installation.html` etc. rather than `installation/index.html`. The
rendered HTML, however, uses extensionless links like
`/beads/getting-started/installation`. In offline mode lychee resolves
those literally against `website/link-check-root/` and reports them as
missing files.

Adding `--fallback-extensions html` tells lychee to retry with the
`.html` suffix when a bare-path target is not found, matching how the
deployed GitHub Pages site actually serves these URLs.

Verified locally: lychee reported 26,877 link errors before this change
and 0 after. Restores the Deploy Documentation workflow which has been
red on main since 2026-04-07.
2026-05-05 20:17:54 -07:00

103 lines
2.8 KiB
YAML

name: Deploy Documentation
on:
push:
branches:
- main
paths:
- 'website/**'
- 'scripts/generate-llms-full.sh'
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
concurrency:
group: "pages"
cancel-in-progress: true
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
- name: Setup Node.js
uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
with:
node-version: 24
cache: 'npm'
cache-dependency-path: website/package-lock.json
- name: Install dependencies
working-directory: website
run: npm ci
- name: Generate llms-full.txt
run: ./scripts/generate-llms-full.sh
- name: Build website
working-directory: website
run: npm run build
- name: Prepare link check (map baseUrl /beads/ to build output)
run: |
mkdir -p website/link-check-root
ln -s "$PWD/website/build" website/link-check-root/beads
- name: Check internal links
uses: lycheeverse/lychee-action@8646ba30535128ac92d33dfc9133794bfdd9b411 # v2
with:
args: |
--verbose
--no-progress
--offline
--include-fragments
--timeout 30
--root-dir website/link-check-root
--fallback-extensions html
--exclude-path 'website/build/search/**'
website/build
fail: true
- name: Check external links (non-blocking)
uses: lycheeverse/lychee-action@8646ba30535128ac92d33dfc9133794bfdd9b411 # v2
continue-on-error: true
with:
cache: true
args: |
--verbose
--no-progress
--timeout 30
--scheme https
--scheme http
--exclude 'localhost'
--exclude '127.0.0.1'
--exclude 'tree/main'
--exclude 'example.com'
--exclude 'mailto:'
--exclude-path 'website/build/search/**'
website/build
- name: Upload artifact
uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5
with:
path: website/build
deploy:
# Guard: deploy should only run in the canonical repository (not in forks)
if: ${{ github.repository == 'gastownhall/beads' }}
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
needs: build
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5