Skip to Content
How it was builtDesign specsDocumentation site (docs.antmejia.com)

Documentation site (docs.antmejia.com)

Issue: #44 (sub-issue of #11). Status: design approved in conversation 2026-10-06; this spec is awaiting review.

Goal

The footer’s Documentation link opens a real docs site at https://docs.antmejia.com, built with Nextra 4 as its own Vercel project, containing hand-written engineering docs plus a “How it was built” section generated from the repo’s design specs and plans.

Non-goals

  • No change to the portfolio app’s install, build or Vercel project.
  • No Yarn workspaces migration.
  • No API reference generation (TypeDoc) and no component docs (Storybook already covers components at storybook.antmejia.com).
  • No claims or content the owner has not written; product copy comes from PRODUCT.md, the README and the code.

Audience

Engineering peers evaluating how the site is built (secondary persona in PRODUCT.md), plus a process section showing how work was specified and planned.

Why Nextra 4

Compatible with this stack (peer deps: Next >=14, React >=18; the repo is on Next 15.5, React 19.1). Fumadocs was rejected because fumadocs-core 16 requires Next 16 and React >=19.2. Docusaurus/Starlight were not evaluated further since they add a second framework. Search (Pagefind), sidebar, table of contents and dark mode are included.

Structure

  • docs-site/: a standalone Next app, not a workspace. Own package.json and yarn.lock, exact-pinned dependencies (save-exact), own tsconfig.json.
  • The root tsconfig.json excludes docs-site/. Root ESLint already lints only src/**. Prettier’s format:ci covers it; generated content is listed in .prettierignore.
  • Renovate picks up the nested package.json automatically.
  • docs-site/content/ holds the MDX pages; docs-site/content/how-it-was-built/ is generated (gitignored).

Content

Hand-written pages (MDX), from existing material:

  1. Overview: product, stack, principles (PRODUCT.md).
  2. Architecture: folder layout, how routes, content modules and partials compose.
  3. Content model: how to edit roles, skills, education and the resume PDF.
  4. Styling system: tokens, sprinkles, PageShell.
  5. Quality gates: CI checks, Storybook tests, unit tests.
  6. Release process: PR flow, release-please, production branch, rollback (mirrors the README section; the README stays the entry point and links here).

How it was built (generated)

  • Source of truth stays in docs/superpowers/{specs,plans}/.
  • docs-site/scripts/sync-process-docs.mjs runs before dev and build. It copies each file into content/how-it-was-built/, derives the page title from the first # heading, strips nothing else, and writes an index grouped by specs and plans, newest first (dates come from the YYYY-MM-DD- filename prefix).
  • Specs and plans contain raw <, { and task-list syntax that MDX can fail on. The script must emit plain Markdown pages (or escape as needed). First implementation task: verify this renders with a real spec and plan before building anything else.

Look

Within what the theme allows: logo (the AMI mark), fonts (Prompt body, Italiana headings, Saira display) via the theme’s CSS variables, navy accent derived from the site tokens. Light by default with the theme’s dark toggle. No claim of visual parity with the portfolio; it is a docs site.

Deploy

  • New Vercel project, same GitHub repo, Root Directory docs-site/, framework Next.js, name for example looking-glass-docs.
  • Production branch: production (same as the portfolio), so the docs describe what is live and update when a release is promoted. Pushes to main do not deploy docs.
  • Ignored build step (docs-site/vercel.json → ignoreCommand → docs-site/scripts/vercel-ignore.sh): build only on the production branch, and only when docs-site/ or docs/ changed since the last deployed commit (git diff --quiet "$VERCEL_GIT_PREVIOUS_SHA" HEAD -- docs-site docs, building if the variable is unset). A plain HEAD^ comparison is wrong here because the production branch fast-forwards over many commits. Non-production branches are skipped; CI covers PR builds.
  • Domain: docs.antmejia.com added to the project by me; the owner adds the Cloudflare CNAME (DNS only), as was done for Storybook.
  • Quota: Hobby deployments are shared account-wide; the path filter keeps docs deploys rare.

CI

Check PR gains a step that installs and builds the docs (yarn --cwd docs-site install --frozen-lockfile, then yarn --cwd docs-site build) so a broken docs build cannot merge.

  • src/content/links.ts: Documentation points at https://docs.antmejia.com (external, new tab). The footer already renders external links.
  • PRODUCT.md: remove the stale statement that docs run as a separate service from the old GKE setup, and state the new reality.
  • README: link to the docs site from the Deployment section.

Testing

  • docs-site builds locally and in CI; Pagefind index is produced.
  • Playwright probe against the built docs: home 200, sidebar present, search returns a known term, one How-it-was-built page renders its code blocks and checkboxes without errors, no console errors.
  • Impeccable audit of the themed site (contrast, tap targets, keyboard) once built.
  • After the release that carries it: https://docs.antmejia.com returns 200 in production and the footer link opens it.

Risks and open decisions

  • MDX vs. raw spec/plan Markdown (see above); fallback is rendering those pages as pre-processed Markdown with escaped angle brackets and braces.
  • Theme customization limits: Nextra’s theme constrains layout; if the brand fit is poor, fonts and colors are the only guaranteed levers.
  • Owner steps: Cloudflare CNAME for docs.antmejia.com. Everything else (Vercel project, domain attachment, ignore script, CI step) is done in the repo or through the Vercel tools.
  • Docs lag releases by design (production branch); the “How it was built” section therefore shows specs only once released.
Overview/resume page, PDF download and optional email capture