docs

@temples/docs

The documentation site of the temples packages — built with temples itself.

How it works

content/*.md  ──Bun.markdown──▶  HTML fragments
                                     │
layout.html  ──@temples/ssr prepare()─▶  www/<slug>.html  +  www/assets/style.css
content/*.md  ──raw copy─────────────▶  www/<slug>.md  (plain-text counterpart)
                                     │
                                     └──▶  www/llms.txt  (agent index, links the .md files)

• content/*.md — one file per page. The front-matter block carries title, description, and order (nav ordering). A page with hidden: true is built but stays out of the navigation and llms.txt.
• content/404.md — the 404 error page, kept out of the navigation by hidden: true.
• layout.html — a temples template: the nav iterates site.pages (data-iterate), the page body is injected with data-bind="html=page.content". The head declares the markdown export of the page with <link rel="alternate" type="text/markdown">, kept only while data-render-if="page.markdownUrl" is truthy — hidden pages carry an empty markdownUrl, so they emit no link. It also declares <link rel="describedby" href="llms.txt">, the agent index covering the site, as recommended by llmstxt.org.
• src/markdown.ts — the only module that touches Bun.markdown (an unstable Bun API), so a parser swap stays a one-file change.
• src/build.ts — the pipeline. buildSite() is exported for tests; the script runs it when executed directly. It copies every visible page as raw markdown next to its HTML file.
• src/serve.ts — serves www/ with a Bun file route for the root, and a fetch handler for every other path. When the path does not name a file in www/, the handler serves 404.html with status 404.

Commands

Run these commands from inside packages/docs/. The build regenerates www/ completely, so never edit its files by hand.

bun run build    # build the site into www/
bun run serve    # serve www/ at http://localhost:4173
bun test         # the build has a smoke test (build.test.ts)

Deployment

The site is a plain static output: any static host works, with www/ as the publish directory and bun install && bun run build:docs as the build command.

• GitHub Pages — .github/workflows/deploy-docs.yml deploys on every push to master. Pages serves the site under a subpath (/temples/), which the build supports because all asset and page links are relative. Pages also uses www/404.html as its error page.
• Vercel / Netlify / Cloudflare Pages — create a project pointed at this repository with:
  • build command: bun install && bun run build:docs
  • output directory: packages/docs/www
• LLM agents — the build emits www/llms.txt, an index of every page with absolute links to its raw markdown (<slug>.md), so agents fetch plain text instead of HTML.