Documentation application

The docs site is a separate Next.js/Fumadocs app at docs/ in the same repository. It uses the actual set-me-up-docs source interface: floating navigation, left sidebar, article column, right table of contents, mobile menu, search, copy/share controls, keyboard shortcuts, themes and page transitions.

Source and branding

docs/reference.json pins the set-me-up-docs revision. docs/upstream.json records the retained asciicn source and verifies unchanged files. Keep the reference layout intact; adapt identity and content rather than rebuilding an approximation. Preserve ASCIICN-LICENSE and SET-ME-UP-DOCS-LICENSE.

Portfolio colors are isolated in docs/styles/brand.css: ink, paper and stone. The portrait, wordmark and Inter font identify Nicholas Adamou. The documentation app has its own CSS and dependencies so it does not alter the portfolio shell.

Content pipeline

Author Markdown in docs/src/. docs/navigation.json defines groups, labels and page order. docs/scripts/generate-content.ts creates MDX and sidebar metadata under docs/content/docs/, extracts page titles and descriptions, rewrites local Markdown links, and converts Mermaid fences to rendered diagrams.

Do not edit generated MDX. Regenerate after changing source pages. The validator rejects unlisted guides, stale content and broken internal page links. Code fences remain literal; article titles come from frontmatter rather than a duplicate H1. Markdown exports expand diagrams back into Mermaid source.

Request routing

The public URL stays on the portfolio's origin even though the docs application is deployed independently. The portfolio uses Next.js rewrites to send document, Markdown and namespaced asset requests to the docs service. Its own Markdown proxy passes those requests through so it cannot replace a docs response with a portfolio missing-page response.

Use a full document navigation when crossing between the portfolio and docs zones. Within the docs app, ordinary Next.js links retain fast page navigation. The separate asset prefix prevents either application from loading the other application's runtime or styles by mistake.

Preview and validation

Run bun run docs:dev from the repository root inside Flox and open http://localhost:3000/docs. The portfolio runs on port 3000 and proxies /docs to the docs service on port 8000. bun run docs:check checks content, upstream integrity, lint, tests and the production build. The docs smoke script checks every generated route, Markdown exports, content negotiation and missing-page status codes.

Delivery

Use a separate Vercel project linked to github.com/nicholasadamou/nicholasadamou.com, with Root Directory docs, Next.js, Node.js 24 and the committed docs/vercel.json build settings. The public address is https://nicholasadamou.com/docs; the portfolio rewrites docs and docs asset requests to this independent deployment. DOCS_ORIGIN can override the upstream docs service for testing. Production follows main; other branches receive preview deployments. The portfolio project remains independent. The portfolio routes /docs, Markdown mirrors and /docs-static assets to this app. A unique asset prefix prevents collisions with the portfolio Next.js runtime. Use a plain anchor for links crossing between the portfolio and docs apps. Production canonical links, sharing and Markdown exports use nicholasadamou.com.

The Documentation GitHub workflow validates the app. Vercel handles deployment; GitHub Pages is no longer used for the docs site.