Docs publishing

The documentation site is a Docusaurus site. The prose lives at the repository root in docs/, next to the code it documents; website/ holds only the site machinery (config, React components, styles), so the Python project root stays free of Node tooling.

How it is published

Everything is driven by the docs.yaml workflow:

Trigger	What happens
Pull request touching docs/ or website/	Type-check and build only — a broken link or a bad MDX page fails the PR.
Push to main	Build and publish to GitHub Pages.
Manual Run workflow	Same as a push to main.

Publishing uses the GitHub Actions Pages source, so there is no gh-pages branch and no bot commits in the history. The artifact the build produces is handed straight to actions/deploy-pages.

Reviewing a pull request's docs

GitHub Pages allows exactly one deployment per repository, so a pull request cannot have its own preview URL without giving up the Actions publishing source and going back to a gh-pages branch. Instead, every PR build attaches the finished site to the workflow run:

1. Open the PR's Docs check → Summary → Artifacts → docs-site-pr-<number>.
2. Unpack it over website/build.
3. cd website && npm run serve.

Use npm run serve rather than a generic static server: the site is published under /ha-power-insight/, and a server rooted elsewhere will 404 every asset.

If preview URLs ever become worth the setup, an external host (Cloudflare Pages, Netlify) is the way to get them — it builds fork PRs in its own sandbox, which is the part that is genuinely awkward to do safely from this repository.

One-time Pages setting

Settings → Pages → Build and deployment → Source: GitHub Actions.

This replaced the old Deploy from a branch → gh-pages setting, which the previous MkDocs + mike setup required.

Working on the docs locally

cd website
npm install
npm start          # dev server with hot reload on http://localhost:3000

Two checks worth running before pushing, because CI runs both:

npm run typecheck  # the anchor-diagram component and the case data
npm run build      # catches broken links and broken heading anchors

The build treats broken internal links and broken anchors as errors, not warnings. That is deliberate: the anchor-case pages are a specification, and a link that silently rots undermines the point.

Markdown vs MDX

markdown.format is set to detect:

• .md is parsed as plain CommonMark. Braces and angle brackets in prose and code spans are left alone, which is what most pages want.
• .mdx is parsed as MDX and can import and render React components.

Only pages that actually embed a component — the anchor-case pages, and the landing page — need to be .mdx. Prefer .md for everything else.

Versioning

The site currently publishes a single version. The MkDocs site was versioned with mike; that history stays browsable on the old gh-pages branch but is no longer updated.

Docusaurus versions by snapshotting: npm run docusaurus docs:version 1.0 copies the current docs/ into website/versioned_docs/version-1.0/. Worth turning on when the integration hits 1.0 and the docs need to describe more than one supported release — before that it mostly adds ceremony.

If you do enable versioning

The anchor-case JSON lives under docs/spec/anchors/ precisely so it gets snapshotted with the prose. The component that renders it lives in website/src/ and is shared across all versions, which is why every page passes its case data in as a prop rather than letting the component import it. Keep that split, or an old version's page will start rendering with today's data.