website/ — Docusaurus site for mecatl.dev

The Docusaurus infra lives here. Content does not. All .md doc files live in ../user-docs/ (repo root user-docs/). The site simply points its docs plugin at that directory:

// docusaurus.config.ts
docs: { path: '../user-docs', routeBasePath: '/docs', ... }

Do not put new docs in website/. Edit user-docs/.

Commands

Use the root Taskfile's site: namespace — not npm run from inside this directory:

task site:dev       # start dev server at http://localhost:3001 (background)
task site:build     # full build into website/build/ (catches broken links)
task site:stop      # stop the dev server
task site:typecheck # TypeScript check
task site:format    # prettier --write over user-docs/ (see Formatting below)
task site:clear     # wipe .docusaurus/ and build/

task site:build is the authoritative broken-link check. The site is configured with onBrokenLinks: 'throw' and onBrokenMarkdownLinks: 'throw', so a build failure means a link is broken, not a warning.

Formatting

task site:format runs prettier over ../user-docs/ for normalization (consistent prose wrapping, list/table spacing, fence style). It is not enforced in CI — nothing fails a PR for unformatted markdown. Run it before committing sizeable prose edits if you want the diff to stay clean; skip it for small, targeted changes.

user-docs/.prettierignore excludes the generated reference pages (reference/server-cli.md, reference/configuration.md, reference/typescript-sdk-api/core.md, reference/typescript-sdk-api/node.md) so prettier never fights their own generators — see ../user-docs/AGENTS.md.

Prettier resolves .prettierignore relative to the invoking process's cwd, not by walking up from each file the way .prettierrc config resolution does. The format npm script in website/package.json pins this explicitly (--ignore-path ../user-docs/.prettierignore) because it targets user-docs/ from website/'s cwd. Running prettier directly from inside user-docs/ picks up its .prettierignore by prettier's own default behavior and needs no flag; running it from anywhere else with user-docs as a path argument does not, and will silently reformat the generated pages if the flag is missing.

Link convention

Use content-root-relative .md paths for all cross-document links. These survive slug renames, render correctly in GitHub's markdown preview, and are portable if routeBasePath ever changes.

Pattern

[The agent loop](/features/sessions/agent-loop.md)
[Overview](/building/go/extension-points/index.md)
[Cloud-native harness](/cloud-native-harness.md)

The leading / resolves from the docs content root (user-docs/), not the site root. Docusaurus strips the .md extension when building URLs.

For same-directory siblings, relative .md is fine

<!-- inside getting-started/demo.md -->
[Build your first agent](./first-agent.md)

What NOT to use

Why cross-section relative paths break

Docusaurus v3 resolves ../ traversals from index.md files based on the folder location rather than the file location, causing the traversal to land one level too high. Using content-root-relative paths (leading /) sidesteps this entirely.

Published URL changes

Do not move, rename, or remove a published page as an incidental part of an edit. When a URL change is necessary, the pull request must either preserve the old URL with a redirect or explain why no redirect is needed, such as when the page was never published.

URL redirects use Vercel HTTP redirects. Declare them in vercel.json, verify both the old and canonical URLs against a Vercel deployment, and keep the old path while published inbound links may still use it.

Stubs for unwritten sections

onBrokenLinks: 'throw' means you cannot link to a doc that doesn't exist yet. Before adding a link to a planned-but-not-yet-written doc, create a stub:

---
sidebar_position: 1
title: My planned page
---

:::note[Coming soon]

This page is being written. Check back soon.

:::

Any new section directory also needs its index.md stub before intro.md (or any other doc) can link to it.

Sidebar

The sidebar is fully autogenerated from the user-docs/ directory structure. Control order with sidebar_position in frontmatter. No manual sidebar editing is needed or wanted — sidebars.ts is intentionally minimal.

Config notes

• Dark-only. colorMode.disableSwitch: true, defaultMode: 'dark'. Don't use assets that only work on a light background.
• Mermaid. @docusaurus/theme-mermaid is installed. Use mermaid fenced code blocks freely — they render as diagrams.
• Admonitions. Custom titles require bracket syntax: :::note[My Title]. Blank lines inside the block are required.
• Search. @easyops-cn/docusaurus-search-local is wired up. It indexes user-docs/ automatically; no config needed for new pages.

Writing user-docs

The human-facing authoring and information-architecture contract lives in ../user-docs/AGENTS.md. Keep content in user-docs/ and site infrastructure in website/.