Writing & Content Workflows

Use when building markdown-driven docs / blog sites with mizchi/astra. Astra is a static-site generator first — astra build writes a pure-static tree to disk and astra dev runs a local preview server. The Mars-middleware form (mizchi/astra/middleware) is a secondary shape for when you need to mount the same content on a long-running server (e.g. sol). astra build itself does not open a network listener and (as of 0.22.3) no longer instantiates a Mars Server — buildtodisk calls Middleware::renderurl(url) directly — so the typical deploy is "build once, serve from any static host" (CF Workers Static Assets, GitHub Pages, S3, etc.). Covers (a) the file-to-URL routing rules under docs/ (every .md becomes a route; index.md becomes the directory root; ja/ and other locale dirs are i18n branches), (b) astra.config.json fields (docsdir, outdir, nav, sidebar, i18n, islands, spaRoutes, deploy, headSnippets), (c) per-page metadata via frontmatter (title, description, layout, sidebar, revalidate for ISR — the last one only matters when served from Mars) and page.json (ssr, renderer, spa, fallbackBehavior, staticParams), (d) three ways to drop components onto a page — TSX with React renderToString SSR, MoonBit .mbt with pub fn render() -> Node[Unit], or client-side web components in the islands directory, (e) when to reach for the middleware mount instead (sol embedding, on-demand revalidation), and (f) how this composes with sol (no edge: astra has no sol dependency).

Use whenever working with mizchi/luna in the luna.mbt repo — writing CSR examples, fixing reactivity bugs (effects re-running on unrelated signal changes), adding new luna features, or onboarding to luna's mental model. This is the unified entry point; pick the right reference page below for the specific situation.