Packyard documentation site

Public docs at packyard.dev/documentation. TanStack Start app that renders the markdown in content/ with Shiki syntax highlighting and a Pagefind static search index. Sibling repo to packyard (the product) and usepackyard/website (the marketing site).

Adding a doc

1. Create content/<slug>.md with frontmatter:

   ---
   title: My new page
   description: One sentence used for <meta description> and OG.
   order: 30
   updated: 2026-04-27
   ---

2. Add the slug to src/lib/routes.ts so it shows up in the sidebar, sitemap, and prerender list.

3. bun run dev and verify it renders at http://localhost:3001/documentation/<slug>.

Local development

bun install
bun run dev   # http://localhost:3001/documentation

The dev server hot-reloads markdown edits.

Build

bun run build   # vite build → Nitro prerender → Pagefind index

The build prerenders every doc URL into static HTML and runs Pagefind against .output/public/. The resulting index lives at .output/public/pagefind/. The Nitro server is what actually serves requests; static HTML is the prerender cache.

Deploy

Production: packyard.dev/documentation/* is routed by Traefik to this container. See applications/packyard-docs/ in the k8s-production-cluster repo for the K8s manifests; the GitHub Action in this repo builds the image, pushes to GHCR, and bumps the digest on main.

Workspace dev: the parent usepackyard/ workspace's docker-compose.yml includes a docs service with the matching Traefik labels; make up from there brings everything (website + product + docs) up at once on packyard.test.

Repo conventions

• content/ — markdown source. The only thing non-developers should ever need to edit.
• src/routes/documentation/$slug.tsx — splat route. Reads the matching content/<slug>.md server-side.
• src/lib/markdown.server.ts — unified pipeline (server-only).
• src/lib/routes.ts — single source of truth for the slug list. Sidebar, sitemap, and prerender all consume it.
• src/lib/seo.ts — head/meta builder mirroring the marketing site so canonical/OG/Twitter tags stay consistent across both apps.
• src/components/ — UI: brand-matched header/footer mirrored from the marketing site, plus DocsLayout / Sidebar / ToC / SearchBox.