# 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 o



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 [#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 [#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 [#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.

```mermaid
"sequenceDiagram\n    participant Browser\n    participant Portfolio as Portfolio at nicholasadamou.com\n    participant Docs as Separate docs deployment\n    Browser->>Portfolio: GET /docs/features/homepage\n    Portfolio->>Docs: Forward the docs route\n    Docs-->>Portfolio: Rendered documentation HTML\n    Portfolio-->>Browser: Same-origin response\n    Browser->>Portfolio: GET /docs-static/_next/... assets\n    Portfolio->>Docs: Forward namespaced asset request\n    Docs-->>Browser: Documentation CSS and JavaScript"
```

| Public path                  | Responsibility                                         |
| ---------------------------- | ------------------------------------------------------ |
| `/docs` and `/docs/...`      | Documentation pages and same-zone navigation           |
| `/docs.md` and `/docs/...md` | Human-readable Markdown exports                        |
| `/llms.md/docs/...`          | The docs application's explicit Markdown mirrors       |
| `/docs-static/...`           | Docs JavaScript, CSS and generated font assets         |
| `/docs-assets/...`           | Docs portrait, social image and other public resources |

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 [#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 [#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.