@writedocs/generator 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Gabriel Raeder
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,17 @@
+# Writedocs
+
+A static site generator for documentation: a `writedocs.json` config + a folder of MDX/Markdown in, a fully static site out. Built on [Astro](https://astro.build), in the spirit of Docusaurus/Mintlify.
+
+## Quickstart
+
+```bash
+npm install -g @writedocs/generator
+
+cd my-docs   # any folder containing writedocs.json + docs/
+writedocs dev
+writedocs build
+```
+
+The npm package is `@writedocs/generator`; the CLI command it installs is still `writedocs` (see the `bin` field in `package.json`).
+
+`npx @writedocs/generator init/dev/build` still works too, for a one-off run with no install at all.

package/astro.config.mjs

@@ -0,0 +1,419 @@
+import { defineConfig } from 'astro/config';
+import mdx from '@astrojs/mdx';
+import react from '@astrojs/react';
+import icon from 'astro-icon';
+import sitemap from '@astrojs/sitemap';
+import tailwindcss from '@tailwindcss/vite';
+import path from 'node:path';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import matter from 'gray-matter';
+import { unified } from '@astrojs/markdown-remark';
+import {
+  transformerMetaHighlight,
+  transformerMetaWordHighlight,
+  transformerNotationHighlight,
+  transformerNotationWordHighlight,
+  transformerNotationFocus,
+  transformerNotationDiff,
+  transformerNotationErrorLevel,
+} from '@shikijs/transformers';
+import { codeBlockTransformer } from './src/lib/shiki-code-block.js';
+import { rehypeMermaid } from './src/lib/mermaid-rehype.js';
+import remarkMath from 'remark-math';
+import rehypeKatex from 'rehype-katex';
+import { remarkAutoHydrateSnippets } from './src/lib/mdx-auto-hydrate.js';
+import { remarkInjectBuiltinComponents } from './src/lib/mdx-inject-builtins.js';
+import { remarkTitleAnchorIds } from './src/lib/mdx-title-anchor-ids.js';
+import { remarkSubstituteVariables } from './src/lib/mdx-substitute-variables.js';
+import { writedocsTempDir, writedocsBuildStagingDir } from './src/lib/writedocs-temp-dir.js';
+import { stylesAssetFallback } from './src/lib/styles-asset-integration.js';
+import {
+  loadDocsConfig,
+  resolveCodeblockTheme,
+  resolveCodeblockLangAlias,
+  resolveSiteUrl,
+  normalizeEntryId,
+  findAllPages,
+} from './src/lib/config.ts';
+
+const contentDir = process.env.WRITEDOCS_CONTENT_DIR || process.cwd();
+// See writedocsBuildStagingDir()'s own comment (writedocs-temp-dir.js) for
+// why `outDir` below points here instead of directly at contentDir/dist -
+// short version: keeps Astro's own build executing inside the package (so
+// its dependencies' own module resolution keeps working), while build.js
+// does the actual cross-filesystem-safe copy into contentDir/dist as an
+// explicit final step once the build itself is done.
+const packageRoot = process.env.WRITEDOCS_PACKAGE_ROOT || path.dirname(fileURLToPath(import.meta.url));
+
+// Read here (rather than deferred to page-render time, where
+// loadDocsConfig() is also called from [...slug].astro) specifically so
+// a site's writedocs.json can pick its own Shiki theme names - astro.config.mjs
+// is where Shiki itself actually gets configured, and dev.js/build.js
+// already guarantee writedocs.json exists and is valid JSON (preflightCheck())
+// before runAstro() ever gets this far, so letting loadDocsConfig() throw
+// its own validation error on a malformed writedocs.json here is consistent
+// with how every other consumer of it in this codebase behaves - no
+// special-casing needed.
+const docsConfig = loadDocsConfig(contentDir);
+// resolveCodeblockTheme() is the single source of truth for the
+// github-light/github-dark fallback - also used by ApiReferencePanel.astro
+// for its own separate <Code/> usages (which don't inherit
+// markdown.shikiConfig at all), so both stay in sync off the same
+// writedocs.json field.
+const codeblockTheme = resolveCodeblockTheme(docsConfig);
+// resolveCodeblockLangAlias() - see its own comment in lib/config.ts for
+// why this exists: some bundled Shiki grammars (mdx, notably) parse
+// without error but produce no real token differentiation under this
+// theme, so a ```lang fence renders as one flat color instead of
+// highlighted. Remaps a fence's language tag to a better-behaved grammar
+// before Shiki ever sees it - built-in mdx -> jsx default, plus whatever
+// a site adds of its own under writedocs.json's styles.codeblocks.langAlias.
+const codeblockLangAlias = resolveCodeblockLangAlias(docsConfig);
+
+// publicDir defaults relative to Astro's --root (always the writedocs
+// package itself - see src/cli/run-astro.js), not the content directory
+// being built. Point it at <contentDir>/public instead so a site's own
+// static assets (logos, favicons, ...) actually get copied/served -
+// falling back to Astro's normal default (<packageRoot>/public, which
+// doesn't exist in this package) when a site has no public/ of its own,
+// since passing a nonexistent publicDir is a hard Astro error.
+const contentPublicDir = path.join(contentDir, 'public');
+
+// Sitemap generation needs an absolute origin to build absolute <loc>
+// entries against - writedocs.json's `domain` field (see resolveSiteUrl() in
+// lib/config.ts) is the single source of truth for that, shared with the
+// canonical/OG/Twitter URL tags BaseLayout.astro renders per-page. A site
+// with no `domain` set (most fixtures, local-only builds) just doesn't
+// get a sitemap.xml at all - @astrojs/sitemap requires Astro's own `site`
+// config to be set and would otherwise throw, and a sitemap of
+// document-relative URLs isn't meaningful anyway.
+const siteUrl = resolveSiteUrl(docsConfig);
+if (!siteUrl) {
+  console.log('[writedocs] No writedocs.json "domain" set - skipping sitemap.xml generation.');
+}
+
+/** Recursively lists every .md/.mdx file under `baseDir` (Node 20's
+ *  recursive readdir, no extra glob dependency needed - matches the
+ *  plain-fs-walk style already used by generate-api-pages.js's
+ *  findHandWrittenOverrides()), or an empty list if the directory doesn't
+ *  exist (e.g. a site with no OpenAPI groups has no generated-docs/ at
+ *  all under writedocsTempDir()). */
+function walkMdFiles(baseDir) {
+  if (!fs.existsSync(baseDir)) return [];
+  return fs
+    .readdirSync(baseDir, { recursive: true })
+    .filter((f) => /\.mdx?$/i.test(f))
+    .map((f) => path.join(baseDir, f));
+}
+
+/** The set of normalized page ids (see normalizeEntryId()) whose
+ *  frontmatter sets `seo.noindex: true` - excluded from sitemap.xml below,
+ *  since listing a page there while also telling crawlers not to index it
+ *  (BaseLayout.astro's <meta name="robots" content="noindex..."> for the
+ *  same flag) would be self-contradictory. Reads frontmatter directly via
+ *  gray-matter rather than astro:content, which doesn't exist yet this
+ *  early in Astro's own startup - the same reason
+ *  generate-api-pages.js's own frontmatter scanning does the same thing.
+ *
+ *  Reuses findAllPages() from lib/config.ts (rather than its own
+ *  hand-rolled walk) for the hand-written-page half of this scan, so it
+ *  always sees exactly the same file set that actually becomes a page in
+ *  the `pages` collection - no risk of the two independently drifting
+ *  apart on which directories get excluded. The fallback id
+ *  (`relativeId` with its extension and any trailing `/index` segment
+ *  stripped) mirrors fileIdForEntry()'s own algorithm in lib/config.ts,
+ *  for a page with no explicit `slug` override. */
+function collectNoindexIds(rootContentDir) {
+  const generatedDocsDir = path.join(writedocsTempDir(rootContentDir), 'generated-docs');
+  const ids = new Set();
+
+  for (const relativeId of findAllPages(rootContentDir)) {
+    const file = path.join(rootContentDir, relativeId);
+    const { data } = matter(fs.readFileSync(file, 'utf-8'));
+    if (!data?.seo?.noindex) continue;
+    const fallbackId = relativeId.replace(/\.mdx?$/i, '').replace(/\/index$/, '');
+    ids.add(normalizeEntryId(data.slug ?? fallbackId));
+  }
+  // Generated OpenAPI stub pages always set an explicit `slug` (see
+  // generate-api-pages.js) - there's no file-path-derived id to fall back
+  // to the way there is for a hand-written page.
+  for (const file of walkMdFiles(generatedDocsDir)) {
+    const { data } = matter(fs.readFileSync(file, 'utf-8'));
+    if (data?.seo?.noindex && data.slug) ids.add(normalizeEntryId(data.slug));
+  }
+  return ids;
+}
+
+const noindexIds = siteUrl ? collectNoindexIds(contentDir) : new Set();
+
+// writedocs.json's `redirects` array -> Astro's own `redirects` config option
+// (a plain `{ [source]: destination }` record - see redirectSchema in
+// lib/config.ts for why there's no `permanent`/status-code field: this
+// package always builds `output: 'static'` with no adapter installed, and
+// Astro's own docs say a static redirect is always a client-side
+// `<meta http-equiv="refresh">` page regardless of what status is asked
+// for). Omitted entirely (rather than passed as `{}`) when a site has no
+// redirects configured, matching the `siteUrl ? [...] : []` pattern above
+// of only opting into a feature's config surface when it's actually used.
+const redirectsConfig = Object.fromEntries(docsConfig.redirects.map((r) => [r.source, r.destination]));
+
+export default defineConfig({
+  ...(siteUrl ? { site: siteUrl } : {}),
+  ...(docsConfig.redirects.length ? { redirects: redirectsConfig } : {}),
+  // Astro's own dev-mode toolbar (the floating pill in the bottom center
+  // of every page - inspect/audit/settings) is a tool for authoring
+  // Astro itself, not something a writedocs site's own reader/author
+  // should see while running `writedocs dev` - it's not exposed as a
+  // writedocs.json option (nothing site-specific to configure here) since
+  // there's no scenario where a writedocs project actually wants it on.
+  // Off in every environment (build never shows it anyway, since it's a
+  // dev-only overlay Astro strips from production output regardless).
+  devToolbar: { enabled: false },
+  // Not contentDir/dist directly - see writedocsBuildStagingDir()'s own
+  // comment (writedocs-temp-dir.js) for why, and build.js for the copy
+  // step that actually gets a finished build from here into the real
+  // <contentDir>/dist a reader/host ever sees. Irrelevant to `astro dev`
+  // (no build output involved), so this applies unconditionally rather
+  // than branching on which CLI command is running.
+  outDir: writedocsBuildStagingDir(packageRoot, contentDir),
+  cacheDir: path.join(writedocsTempDir(contentDir), 'cache'),
+  ...(fs.existsSync(contentPublicDir) ? { publicDir: contentPublicDir } : {}),
+  // icon() reads from whatever @iconify-json/* collections are installed
+  // (see package.json) and inlines only the specific icons a build
+  // actually references as <svg> - the installed collections don't
+  // affect output size beyond that. No `include` config needed: astro-icon
+  // resolves "collection:icon-name" against any installed collection
+  // automatically.
+  integrations: [
+    // markdown.processor (below) carries remarkAutoHydrateSnippets - see
+    // its own comment there for why it's attached there and not here.
+    // Auto-adds `client:load` to every usage of a component imported from
+    // a .jsx/.tsx file (a snippet - see docs/dev/docs/snippets.mdx) that
+    // doesn't already carry its own `client:*` attribute, so a snippet
+    // just works when dropped into a page - nobody using it needs to know
+    // Astro's hydration-directive syntax exists at all, only someone who
+    // wants a *different* strategy (client:visible/idle/only) needs to
+    // write one explicitly.
+    mdx(),
+    // Lets a site's own snippets (see docs/dev/docs/snippets.mdx) be real
+    // .jsx/.tsx React components - hooks and all - dropped straight into
+    // MDX and hydrated client-side as an Astro island (automatically -
+    // see remarkAutoHydrateSnippets above). writedocs' own built-in
+    // components (Callout, Card, ...) stay plain .astro files - this is
+    // purely for snippets a site author writes themselves.
+    react(),
+    icon(),
+    ...(siteUrl
+      ? [
+          sitemap({
+            filter: (page) => {
+              const pathname = new URL(page).pathname;
+              const id = normalizeEntryId(pathname);
+              return !noindexIds.has(id);
+            },
+          }),
+        ]
+      : []),
+    // Lets styles.favicon/styles.logo/styles.background.images/seo.ogImage/
+    // styles.fonts.*.source resolve from anywhere in the project, not just
+    // public/ - see collectConfiguredAssetPaths() (lib/config.ts) for the
+    // field list and styles-asset-integration.js for how it's actually
+    // served/copied.
+    stylesAssetFallback(contentDir),
+  ],
+  output: 'static',
+  // Dual Shiki themes for fenced code blocks (```) in MDX content, so
+  // they switch with the site's own [data-theme] toggle instead of
+  // always rendering Astro's single default (github-dark) regardless of
+  // light/dark mode. Defaults to github-light/github-dark, overridable
+  // per-site via writedocs.json's styles.codeblocks.{light,dark} (any Shiki
+  // theme *name* - see https://shiki.style/themes for the built-in
+  // list - not a custom theme object/JSON file, at least for now).
+  // Astro bakes the "light" theme's colors as the element's base inline
+  // style and adds --shiki-dark/--shiki-dark-bg (etc.) custom
+  // properties alongside it - see the
+  // [data-theme='dark'] :global(.astro-code) override in
+  // BaseLayout.astro that actually swaps to them.
+  markdown: {
+    // Excludes ```mermaid fences from Shiki's own tokenization entirely -
+    // they reach rehypeMermaid (below) as plain, un-highlighted text,
+    // which is what mermaid.js needs to parse and render them into an
+    // actual diagram client-side (see [...slug].astro's initMermaid()).
+    // Syntax-highlighting mermaid's own pseudo-language as if it were
+    // source code would be actively wrong here - the goal is a rendered
+    // diagram, not colored diagram-description text.
+    syntaxHighlight: { type: 'shiki', excludeLangs: ['mermaid'] },
+    // Astro 7's markdown.rehypePlugins (top-level) is deprecated in favor
+    // of passing plugins straight to the `unified` processor itself -
+    // functionally identical (Astro's own deprecated-option shim used to
+    // just forward the top-level array into this exact processor), just
+    // explicit instead of relying on that shim (and the console warning
+    // it prints on every build/dev run). Astro still runs this *after*
+    // its own internal Shiki step (see @astrojs/markdown-remark's
+    // index.js) regardless of which processor plugins are attached to,
+    // so rehypeMermaid still always sees the excluded ```mermaid block
+    // completely untouched by Shiki - exactly the plain
+    // <pre><code class="language-mermaid"> shape it expects to reshape
+    // into mermaid.js's <div class="mermaid"> form.
+    // remarkInjectBuiltinComponents/remarkAutoHydrateSnippets only ever
+    // match JSX/import nodes that exist solely in MDX's extended syntax
+    // tree (see mdx-inject-builtins.js/mdx-auto-hydrate.js) - running them
+    // here rather than passing them to mdx({ remarkPlugins }) avoids that
+    // option's own deprecation warning ("pass it to unified()... MDX will
+    // inherit it" - extendMarkdownConfig defaults to true, so mdx() below
+    // already picks this processor up automatically). Harmless no-op on
+    // plain .md content, which never has an mdxjsEsm/mdxJsxFlowElement
+    // node to match in the first place.
+    // remarkSubstituteVariables is a parameterized plugin (an "attacher"
+    // that takes writedocs.json's `variables` map as its options and returns
+    // the actual transformer) - passed as a unified [attacher, options]
+    // tuple, *not* pre-called (`remarkSubstituteVariables(docsConfig.variables)`
+    // directly in this array). unified's own `use()` always calls
+    // whatever it finds in this array as if it were the attacher itself;
+    // handing it an already-produced transformer function makes unified
+    // invoke *that* with zero arguments during its `freeze()` setup pass,
+    // which crashes deep inside unist-util-visit ("Cannot use 'in'
+    // operator to search for 'children' in undefined") the first time any
+    // MDX page actually builds - a real bug hit and fixed while testing
+    // 25-site-config, not a hypothetical. remarkInjectBuiltinComponents/
+    // remarkAutoHydrateSnippets don't need this tuple form since neither
+    // takes options - they're valid attachers as bare function references.
+    // A site with no `variables` set still gets this plugin instance
+    // (which then no-ops on every file - see its own early-return) rather
+    // than being conditionally omitted, keeping this array's shape static
+    // regardless of writedocs.json content.
+    processor: unified({
+      // remarkMath goes first: it parses $inline$ and standalone $$block$$
+      // math into their own `inlineMath`/`math` mdast node types (mdast-
+      // util-to-hast has built-in support for both, turning them into a
+      // <span>/<div> carrying the raw LaTeX source as a "language-math"
+      // code-like payload for rehypeKatex, below, to render). Running it
+      // before remarkSubstituteVariables means a $...$ span's raw LaTeX
+      // source is no longer a plain `text` node by the time that plugin's
+      // visitor runs (it only visits `text` nodes - see its own comment) -
+      // not that `[[key]]` syntax inside actual LaTeX is a realistic thing
+      // to write, but this keeps the two plugins' node-type boundaries
+      // clean rather than leaving it to chance which one sees a math span
+      // as raw text first.
+      remarkPlugins: [
+        remarkMath,
+        remarkInjectBuiltinComponents,
+        // Runs after remarkInjectBuiltinComponents (order doesn't actually
+        // matter between them - that plugin only ever prepends an import
+        // statement, never touches an existing JSX node's attributes) but
+        // grouped right next to it since both deal with the same set of
+        // built-in component tag names. See its own comment for why this
+        // has to be a whole-document pass rather than logic living inside
+        // Callout.astro/Accordion.astro themselves.
+        remarkTitleAnchorIds,
+        remarkAutoHydrateSnippets,
+        [remarkSubstituteVariables, docsConfig.variables],
+      ],
+      // rehypeKatex renders every math/inlineMath node remarkMath produced
+      // into real KaTeX markup (a <span class="katex">...</span> tree of
+      // MathML + HTML, not an image or client-rendered widget) - fully at
+      // build time, so unlike Mermaid there's no client-side JS or runtime
+      // cost at all, just the one katex.min.css import (BaseLayout.astro)
+      // for layout/glyph styling. Order relative to rehypeMermaid doesn't
+      // matter - they walk disjoint hast node shapes (pre>code.language-
+      // mermaid vs. remarkMath's own math/inlineMath-derived nodes) and
+      // neither plugin's output is visible to the other.
+      rehypePlugins: [rehypeMermaid, rehypeKatex],
+    }),
+    shikiConfig: {
+      themes: codeblockTheme,
+      langAlias: codeblockLangAlias,
+      // The official @shikijs/transformers annotation transformers -
+      // enabled sitewide so any fenced code block can use their meta-
+      // string/comment syntax without per-page opt-in:
+      //   ```js {1,3-5}                  -> transformerMetaHighlight
+      //   ```js /someWord/                -> transformerMetaWordHighlight
+      //   // [!code highlight]            -> transformerNotationHighlight
+      //   // [!code word:someWord]        -> transformerNotationWordHighlight
+      //   // [!code focus]                -> transformerNotationFocus
+      //   // [!code ++] / // [!code --]   -> transformerNotationDiff
+      //   // [!code error] / [!code warning] -> transformerNotationErrorLevel
+      // (comment syntax adapts to the language - # for Python/bash, //
+      //  for JS/etc - see each transformer's own docs at shiki.style).
+      // Plus codeBlockTransformer, writedocs' own transformer for the
+      // copy button, an optional title bar, and wrap/lines/expandable
+      // meta flags - see src/lib/shiki-code-block.js. It runs last so
+      // its `root` hook wraps the <pre> only after every class the
+      // transformers above added to it is already in place - though in
+      // practice this doesn't matter, since all `pre`/`line` hooks
+      // across every transformer run to completion before any `root`
+      // hook runs at all (two separate passes, not interleaved).
+      transformers: [
+        transformerMetaHighlight(),
+        transformerMetaWordHighlight(),
+        transformerNotationHighlight(),
+        transformerNotationWordHighlight(),
+        transformerNotationFocus(),
+        transformerNotationDiff(),
+        transformerNotationErrorLevel(),
+        codeBlockTransformer(),
+      ],
+    },
+  },
+  // Tailwind is available for future/custom content (e.g. hand-authored
+  // MDX) but nothing in writedocs' own components has been migrated to
+  // it - they still use scoped <style> blocks + the --wd-* CSS variables
+  // so per-site writedocs.json theming (colors, and now dark mode) keeps
+  // working. See src/styles/global.css for the one @import that wires
+  // Tailwind's utilities in.
+  vite: {
+    plugins: [tailwindcss()],
+    resolve: {
+      alias: [
+        // Lets a page's MDX write `import Foo from '/snippets/foo.mdx'`
+        // (Mintlify's own snippet-import convention) instead of a
+        // relative path whose "../" depth depends on how deeply nested
+        // the importing page happens to be - see docs/dev/docs/snippets.mdx
+        // for the full feature writeup. Vite's project root is always
+        // packageRoot (this package itself - see run-astro.js), not
+        // contentDir, so a real leading-slash import would otherwise
+        // resolve (and fail to find anything) inside this package
+        // instead of the site's own content directory; this alias
+        // redirects just that one prefix to contentDir/snippets/ instead.
+        { find: /^\/snippets\//, replacement: path.join(contentDir, 'snippets') + '/' },
+        // remarkInjectBuiltinComponents (mdx-inject-builtins.js) auto-
+        // injects `import { Callout, ... } from 'writedocs/components'`
+        // into any .mdx file that uses a built-in component tag without
+        // importing it itself - a real bare specifier Vite has to resolve
+        // as if the .mdx file had written it. package.json's own
+        // `exports: { "./components": "./src/components/index.ts" }`
+        // makes that specifier valid *in principle* (Node's package
+        // self-reference feature - a package importing its own name), but
+        // self-reference only resolves when the importing file is a
+        // descendant of this package's own package.json - true for every
+        // existing fixture (always built from inside this repo/package
+        // tree) but never true for a real consumer's content, which lives
+        // in a completely separate directory in the actual product
+        // architecture (see docs/dev/docs/architecture.mdx) - walking up
+        // from such a file never finds a package.json named "writedocs",
+        // so self-reference fails and Vite reports the bare specifier as
+        // unresolvable ("Rolldown failed to resolve import
+        // 'writedocs/components'"). See BUG.md for the full writeup this
+        // fix comes from.
+        // This alias bypasses self-reference resolution entirely for
+        // that one specifier - Vite's alias matching is a plain string
+        // match against the specifier itself, independent of which file
+        // imported it, so it resolves correctly regardless of where the
+        // content directory actually lives. WRITEDOCS_PACKAGE_ROOT is the
+        // same packageRoot value already set by run-astro.js for
+        // lib/config.ts's fileIdForEntry() to consume - reusing it here
+        // instead of recomputing via import.meta.url keeps there being
+        // exactly one source of truth for "where this package lives" per
+        // astro subprocess. Falls back to this file's own directory
+        // (astro.config.mjs always lives at packageRoot) for anything
+        // that ever imports this config outside that subprocess, e.g. a
+        // future test harness.
+        {
+          find: 'writedocs/components',
+          replacement: path.join(packageRoot, 'src/components/index.ts'),
+        },
+      ],
+    },
+  },
+});

package/bin/writedocs.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import dotenv from 'dotenv';
+import { runDev } from '../src/cli/dev.js';
+import { runBuild } from '../src/cli/build.js';
+import { runInit } from '../src/cli/init.js';
+import { requireBuildKey } from '../src/cli/build-auth.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(__dirname, '..');
+// Read rather than hardcode - a literal version string here silently drifts
+// from package.json's own "version" the moment either one is bumped without
+// the other (exactly what `npm version <bump>` does: it only touches
+// package.json). `writedocs --version` should always reflect what actually
+// got published, not whatever this string happened to say at the time this
+// line was last hand-edited.
+const { version } = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf-8'));
+
+const program = new Command();
+program
+  .name('writedocs')
+  .description('Static site generator for writedocs.json + MDX')
+  .version(version);
+
+program
+  .command('dev')
+  .description('Start a local dev server with hot reload')
+  .argument('[dir]', 'content directory (contains writedocs.json and docs/)', '.')
+  .option('-p, --port <port>', 'port to run on')
+  .action(async (dir, opts) => {
+    await runDev({
+      contentDir: path.resolve(process.cwd(), dir),
+      packageRoot,
+      port: opts.port,
+    });
+  });
+
+program
+  // { hidden: true } keeps `build` out of `writedocs --help` - it's not a
+  // command ordinary users are meant to discover or run themselves. See
+  // src/cli/build-auth.js for the second layer: even someone who knows the
+  // command exists still can't run it without the right key.
+  .command('build', { hidden: true })
+  .description('Build a static site into <dir>/dist')
+  .argument('[dir]', 'content directory (contains writedocs.json and docs/)', '.')
+  .option('-k, --key <key>', 'build authorization key (or set WRITEDOCS_API_KEY)')
+  .action(async (dir, opts) => {
+    const contentDir = path.resolve(process.cwd(), dir);
+    // Project-scoped, not global: a .env sitting next to this project's own
+    // writedocs.json (WRITEDOCS_KEY_SERVER_URL, WRITEDOCS_API_KEY) is picked
+    // up automatically, so build doesn't need those exported by hand every
+    // session. dotenv never overwrites a var already set in the real
+    // environment - an explicit `export`/CI secret still wins over the file.
+    dotenv.config({ path: path.join(contentDir, '.env'), quiet: true });
+    await requireBuildKey(opts.key || process.env.WRITEDOCS_API_KEY);
+    await runBuild({ contentDir, packageRoot });
+  });
+
+program
+  .command('init')
+  .description('Scaffold a writedocs.json and starter docs/ folder')
+  .argument('[dir]', 'directory to scaffold into', '.')
+  .action(async (dir) => {
+    await runInit({ targetDir: path.resolve(process.cwd(), dir) });
+  });
+
+program.parseAsync(process.argv).catch((err) => {
+  console.error(`[writedocs] ${err.message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@writedocs/generator",
+  "version": "0.1.0",
+  "description": "Static site generator for docs — a writedocs.json + MDX folder in, a static site out.",
+  "type": "module",
+  "bin": {
+    "writedocs": "./bin/writedocs.js"
+  },
+  "exports": {
+    "./components": "./src/components/index.ts"
+  },
+  "files": [
+    "bin",
+    "src",
+    "astro.config.mjs"
+  ],
+  "scripts": {
+    "dev": "node bin/writedocs.js dev",
+    "build": "node bin/writedocs.js build",
+    "init": "node bin/writedocs.js init"
+  },
+  "keywords": [
+    "docs",
+    "documentation",
+    "static-site-generator",
+    "mdx",
+    "astro"
+  ],
+  "homepage": "https://github.com/writedocs/writedocs#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/writedocs/writedocs.git"
+  },
+  "bugs": {
+    "url": "https://github.com/writedocs/writedocs/issues"
+  },
+  "author": "Gabriel Raeder",
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@apidevtools/swagger-parser": "^12.1.0",
+    "@astrojs/markdown-remark": "7.2.2",
+    "@astrojs/mdx": "^7.0.5",
+    "@astrojs/react": "^6.0.2",
+    "@astrojs/sitemap": "^3.7.3",
+    "@iconify-json/bi": "^1.2.7",
+    "@iconify-json/fa6-brands": "^1.2.6",
+    "@iconify-json/fa6-solid": "^1.2.4",
+    "@iconify-json/heroicons": "^1.2.3",
+    "@iconify-json/ion": "^1.2.7",
+    "@iconify-json/lucide": "^1.2.116",
+    "@iconify-json/mdi": "^1.2.3",
+    "@iconify-json/ri": "^1.2.10",
+    "@iconify-json/simple-icons": "^1.2.89",
+    "@iconify-json/tabler": "^1.2.35",
+    "@shikijs/transformers": "^4.3.1",
+    "@tailwindcss/vite": "^4.3.2",
+    "astro": "^7.2.2",
+    "astro-icon": "^1.1.5",
+    "commander": "^15.0.0",
+    "dotenv": "^17.4.2",
+    "gray-matter": "^4.0.3",
+    "katex": "^0.16.47",
+    "mermaid": "^11.16.0",
+    "pagefind": "^1.5.2",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "rehype-katex": "^7.0.1",
+    "remark-math": "^6.0.0",
+    "shiki": "^4.3.1",
+    "tailwindcss": "^4.3.2",
+    "zod": "^4.4.3"
+  },
+  "engines": {
+    "node": ">=20.3.0"
+  }
+}