mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-08-27 14:17:10 -04:00
3c10e8ff00
## Description The repo published **two** documentation sites from two source trees: ``` docs/ -> Next.js/Fumadocs -> headroom-docs.vercel.app <- canonical wiki/ -> MkDocs -> gh-pages branch -> github.io/headroom <- orphan ``` The Vercel site is what the README badge and **every** README deep link point at, and what `pyproject.toml` names as both `Homepage` and `Documentation`. The Pages site is referenced from **nowhere** in the repo — not README, not `pyproject`, not `CLAUDE.md`, not any docs page. I grepped for `github.io` and `gh-pages` across all of them and got zero hits. So it was costing work and causing breakage while nobody was reading it: - **Every documented change had to be written twice.** This session I wrote the same configuration content into `docs/content/docs/configuration.mdx` *and* `wiki/configuration.md`. That's the tax, and it compounds silently — the two drift and no one notices which is stale. - **It broke the Vercel deployment.** Each Pages deploy runs `mkdocs gh-deploy --force`, force-pushing `gh-pages`. Vercel's Git integration then tries to build that branch with Root Directory `docs`, which fails: *"The specified Root Directory `docs` does not exist"* — because `gh-pages` holds only the rendered site (`.nojekyll`, `404.html`, …). Timing was exact: ```text 23:06:44 maina9a2fbd7ci(docs): ... (#2746) 23:07:51 gh-pages9cd8775cDeployeda9a2fbd7with MkDocs <- 67s later ``` - The same workflow also carried the `deploy-vercel` job that failed 30 times on main without ever deploying (removed in #2746). ## Changes Made - Removed the `validate-mkdocs` and `deploy-github-pages` jobs, and `mkdocs.yml`. - What remains is one workflow that **only validates** the Next.js build on pull requests. Vercel owns deployment — duplicating that in Actions is exactly what produced the dead `deploy-vercel` job. - Dropped the `push` trigger entirely (nothing deploys from Actions now) and the `wiki/**` / `mkdocs.yml` path filters. - Renamed the workflow `Deploy Documentation` → `Validate Docs`, since it no longer deploys anything. It isn't a required check, so the rename is safe. - Repointed `configuration.mdx`'s Filesystem Contract link from the `wiki/` blob on GitHub to `/docs/filesystem-contract`, which already existed. ## `wiki/` deliberately stays — please read this bit I did **not** delete `wiki/`, even though the ask was to get rid of it. ~14 of its topics have no `docs/` equivalent, and one is significant: ```text 912L wiki/cli.md <- full CLI reference; docs/ has NO cli page 718L wiki/macos-deployment.md 409L wiki/compression.md 370L wiki/transforms.md 345L wiki/integration-guide.md 335L wiki/api.md 292L wiki/sdk.md 231L wiki/learn.md ... ``` `docs/` mentions CLI commands across 27 pages but has no reference page for them. Deleting `wiki/` today would drop 912 lines of CLI documentation on the floor. After this PR `wiki/` is **unpublished markdown**: nothing builds it, nothing deploys it, so **it needs no syncing**. It's a migration backlog, not a parallel site. That gets you the outcome you wanted — one site, one tree to edit — without losing content. ## Type of Change - [x] Code refactoring (no functional changes) ## Testing - [x] Linting passes — workflow YAML parses and resolves to the intended shape: ```text name: Validate Docs jobs: ['validate-nextjs'] triggers: ['pull_request', 'workflow_dispatch'] pr paths: ['docs/**', '.github/workflows/docs.yml'] ``` Verified nothing else depends on the MkDocs pipeline: the only remaining `mkdocs` references in the repo are `CHANGELOG.md` (history) and one unrelated comment in `content_router.py:3329` ("Measured on mkdocs.yml"). No `docs/` page links to a `wiki/` blob any more. CI's `Validate Next.js build` is the real check that the surviving job works. ## Two follow-ups this does NOT do 1. **Disable GitHub Pages and delete the `gh-pages` branch.** Pages is currently enabled (`source: gh-pages`, status `building`) at `https://headroomlabs-ai.github.io/headroom/`. After this PR nothing updates it, so it freezes rather than breaks — and the Vercel `gh-pages` build failure stops recurring because no further force-pushes happen. Actually taking the site down and deleting the branch is a destructive, outward-facing change; I'd rather do that as an explicit step than bundle it here. Nothing in the repo links to it, so the only risk is externally-indexed URLs 404ing. 2. **Migrate `wiki/cli.md` into `docs/` as a CLI reference page**, then the smaller unique topics, then delete `wiki/`. That's content work deserving its own review.
52 lines
1.8 KiB
YAML
52 lines
1.8 KiB
YAML
name: Validate Docs
|
|
|
|
# There is ONE documentation site: the Next.js/Fumadocs app in `docs/`, published
|
|
# at https://headroom-docs.vercel.app by Vercel's own Git integration. That URL is
|
|
# what README and `pyproject.toml` (Homepage, Documentation) point at.
|
|
#
|
|
# This workflow therefore only *validates* — it deploys nothing. Vercel owns
|
|
# deployment; duplicating it here is what produced a `deploy-vercel` job that
|
|
# failed 30 times on main without ever deploying (no VERCEL_* secrets were set).
|
|
#
|
|
# A second site used to be built from `wiki/` by MkDocs and published to GitHub
|
|
# Pages off the `gh-pages` branch. It was linked from nowhere in the repo, it meant
|
|
# every documented change had to be written twice, and each Pages deploy
|
|
# force-pushed `gh-pages` — which Vercel then tried to build, failing with
|
|
# "The specified Root Directory 'docs' does not exist" because that branch holds
|
|
# only the rendered site. Removed. `wiki/` stays in the repo as unpublished
|
|
# markdown pending migration of the pages `docs/` does not yet cover (notably
|
|
# `wiki/cli.md`); nothing builds or publishes it, so it needs no syncing.
|
|
|
|
on:
|
|
pull_request:
|
|
branches: [main]
|
|
paths:
|
|
- 'docs/**'
|
|
- '.github/workflows/docs.yml'
|
|
workflow_dispatch:
|
|
|
|
permissions:
|
|
contents: read
|
|
|
|
jobs:
|
|
validate-nextjs:
|
|
name: Validate Next.js build
|
|
runs-on: ubuntu-latest
|
|
timeout-minutes: 15
|
|
steps:
|
|
- uses: actions/checkout@v6
|
|
|
|
- name: Setup Node.js
|
|
uses: actions/setup-node@v6
|
|
with:
|
|
node-version: '20'
|
|
cache: npm
|
|
cache-dependency-path: docs/package-lock.json
|
|
|
|
- name: Install dependencies
|
|
run: npm ci
|
|
working-directory: docs
|
|
|
|
- name: Build docs
|
|
run: npm run build
|
|
working-directory: docs
|