akadmin/headroom
1
0
Fork 0
mirror of https://github.com/headroomlabs-ai/headroom.git synced 2026-08-27 14:17:10 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions
headroom/docs
History
Tejas Chopra 3c10e8ff00
chore(docs): one documentation site, not two (#2784) 
## 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  main       a9a2fbd7  ci(docs): ... (#2746)
23:07:51 gh-pages 9cd8775c Deployed a9a2fbd7 with 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.
2026-08-04 16:42:49 -07:00
..
app docs: improve discoverability for AI agents and search crawlers 2026-05-13 17:36:06 -07:00
components docs: sync Vercel docs with current code and add in-depth proxy config (#2475) 2026-07-21 16:26:56 -07:00
content/docs chore(docs): one documentation site, not two (#2784) 2026-08-04 16:42:49 -07:00
lib docs: sync Vercel docs with current code and add in-depth proxy config (#2475) 2026-07-21 16:26:56 -07:00
overrides fix: repair release and docs pipelines 2026-04-16 12:53:51 -05:00
screenshots Merge pull request #147 from JerrettDavis/feat/anthropic-usage-insights 2026-04-12 10:54:22 -07:00
.gitignore new docs UI + ts doc coverage 2026-04-12 13:15:58 +06:00
bun.lock fix(deps): remediate dependency CVEs and publish SBOM (#1509) 2026-06-27 15:28:12 -07:00
claude-code-bedrock-headroom.md fix(bedrock): route ARNs via converse, named AWS profiles, and au. re… (#1456) 2026-07-02 22:51:05 -05:00
next.config.mjs new docs UI + ts doc coverage 2026-04-12 13:15:58 +06:00
observability.md fix: remove rtk and lean-ctx CLI context tools (#2677) 2026-07-30 22:59:41 -07:00
package-lock.json deps: bump the npm-minor-patch group across 3 directories with 7 updates (#2276) 2026-07-21 11:21:14 -05:00
package.json deps: bump the npm-minor-patch group across 3 directories with 7 updates (#2276) 2026-07-21 11:21:14 -05:00
platform-feature-matrix.json fix: harden persistent install startup (#1851) 2026-07-10 00:40:34 -04:00
platform-stabilization.md fix: harden persistent install startup (#1851) 2026-07-10 00:40:34 -04:00
postcss.config.mjs new docs UI + ts doc coverage 2026-04-12 13:15:58 +06:00
proxy.ts new docs UI + ts doc coverage 2026-04-12 13:15:58 +06:00
README.md new docs UI + ts doc coverage 2026-04-12 13:15:58 +06:00
source.config.ts docs(ci): add CI/CD flow diagrams (#1062) 2026-06-16 23:05:15 -07:00
tsconfig.json new docs UI + ts doc coverage 2026-04-12 13:15:58 +06:00
vercel.json fix: add Vercel deploy config and workflow for docs site (#1739) 2026-07-14 13:25:18 -04:00

README.md

docs

This is a Next.js application generated with Create Fumadocs.

Run development server:

npm run dev
# or
pnpm dev
# or
yarn dev

Open http://localhost:3000 with your browser to see the result.

Explore

In the project, you can see:

  • lib/source.ts: Code for content source adapter, loader() provides the interface to access your content.
  • lib/layout.shared.tsx: Shared options for layouts, optional but preferred to keep.
Route Description
app/(home) The route group for your landing page and other pages.
app/docs The documentation layout and pages.
app/api/search/route.ts The Route Handler for search.

Fumadocs MDX

A source.config.ts config file has been included, you can customise different options like frontmatter schema.

Read the Introduction for further details.

Learn More

To learn more about Next.js and Fumadocs, take a look at the following resources: