feat(ember-vite): static docs export (.md per page + llms.txt)

[josemarluedke]

Summary

Adds an opt-in static text export to @docfy/ember-vite. When enabled, a production build emits a statically-servable text mirror of the docs alongside the app:

• dist/<page-url>.md — one file per page, at the same path as the live route plus a .md suffix
• dist/llms.txt — links-only index grouped by section, per the llms.txt convention
• dist/llms-full.txt — every page's content concatenated

Why: the docs site is client-rendered only, so a plain HTTP fetch — a crawler, curl, or an AI agent's web-fetch tool — gets the SPA shell rather than content. This makes the docs readable without running JavaScript.

Off by default and build-only; nothing is emitted during vite dev.

docfy({
  staticExport: {
    enabled: true,
    projectName: 'Docfy',
    projectDescription: 'Docfy is a modular JavaScript tool to help build documentation sites.',
  },
});

Links default to root-relative (/docs/getting-started.md), which the llms.txt spec permits — its format definition is only [name](url) — and which stays correct on deploy previews, forks, staging, and localhost. Set the optional siteUrl to emit absolute links instead, for consumers that read the text detached from its origin.

No changes to @docfy/core.

Design notes

The one non-obvious decision worth calling out. The export payload is page.pluginData.staticMarkdown ?? page.markdown, with the frontmatter block stripped.

page.markdown is the raw, untouched file source — set once in Docfy.createPage() and never written by any core plugin (nothing else in the monorepo reads it). Consuming apps that need transformed output — for example replacing a <Signature @component="Button" /> tag with a real Markdown table — set pluginData.staticMarkdown from a Docfy plugin in runAfter.

Doing it in runAfter on Markdown text, rather than mutating the AST, is deliberate: by that point page.ast has already been destructively converted to hast, and page.rendered — which the live SPA route templates are built from — is stringified from that same object. Mutating the AST would corrupt the rendered app. Mutating markdown text is inherently isolated, so no cloning of result.content is needed.

Ordering for both llms.txt and llms-full.txt comes solely from result.nestedPageMetadata, which already encodes section labels and the resolved sections order config.

Changes

File	Change
src/static-export.ts	New. All content logic, no IO — pure and unit-testable.
src/file-manager.ts	Extracted writeTextToPublic(content, fileName); writeJsonToPublic now delegates to it. Behavior preserved for its existing caller.
src/config.ts	Added staticExport to DocfyViteOptions, destructured out so it can't leak into @docfy/core's options.
src/docfy-processor.ts	handleStaticExport(), called from processAll(), gated build-only.
src/index.ts	Option plumbing + eager siteUrl validation via this.error().
README.md	Documented the option and the pluginData.staticMarkdown contract.
test-app-vite/vite.config.mjs	Enabled, as the verification vehicle.

Testing

54 unit tests across 4 files (the package's first tests — vitest was configured but unused). yarn typecheck, yarn lint, and Prettier all clean.

Also verified against a real build of test-app-vite, which sources this repo's own docs/:

• 15 .md files emitted; dist/docs/index.md and dist/docs/ember/index.md correct — trailing-slash index URLs become index.md rather than a broken docs/.md
• llms.txt carries the required # Docfy H1, then the blockquote, then ## Documentation / ## Ember in the configured section order; all 15 root-relative links resolve to real emitted files
• Zero frontmatter leaks across all 15 files, checked against sources that do have frontmatter
• Dev mode confirmed a no-op — no files appear in public/
• Misconfiguration confirmed to fail loudly: an invalid siteUrl (missing scheme, wrong protocol, or carrying a query/fragment) fails the build with a clear message and a non-zero exit, rather than silently emitting broken links

Note

test-app-vite's acceptance suite (testem ci) is currently red and I could not observe it green. It fails with Uncaught ReferenceError: define is not defined in @embroider/virtual/test-support.js — an AMD-loader ordering failure in the test bundle.

This looks pre-existing and unrelated: the failure reproduces identically with this branch's config change reverted, and the only runtime-affecting change here is emitFile calls for standalone .md/.txt assets, which cannot alter module format, chunk graph, or script order. It was not diagnosed, though, so it's worth a look in real CI and probably its own issue — flagging it explicitly rather than letting a red suite get silently inherited.

Follow-ups (deliberately not in this PR)

• frontile side, which this unblocks: emit signature data as JSON, add the <Signature> → Markdown-table plugin writing to pluginData.staticMarkdown, enable the option.
• frontile/docs/superpowers/specs/ sits inside that app's Docfy source root with pattern **/*.md, and core's DEFAULT_IGNORE only covers node_modules/.git/dist — so design docs are already built as docs pages and would land in llms.txt. Needs ignore: ['superpowers/**'].
• Rewriting internal links to .md so an agent crawling the mirror stays in the mirror.
• Generated .gjs templates under test-app-vite/app/templates/docs/ are git-tracked and get rewritten by every build. Pre-existing; worth gitignoring.
• Tighten handleAssets(result: any) / processAll(): Promise<any> now that DocfyResult is imported.

🤖 Generated with Claude Code