On this page
Consume and contribute documentation
Export verified Markdown/JSON and publish the versioned docsp portal.
Status: headless content pipeline supplied in 0.7.0. The first consumer is dotnet-foundation itself. The future ERP app SDK will reuse this contract after its contribution/visibility policy is defined.
Content sources
docs/documentation.json explicitly declares pages, package projects and examples. Markdown holds authored explanations. Stable page IDs produce versioned routes; doc:page-id links are validated and rewritten. Example tokens insert reviewed source fixtures rather than maintaining a second copy of executable code.
Public API symbols come from compiled metadata through Roslyn. The exporter does not execute target assemblies. XML summaries come from compiler XML or source comments matched by compiler documentation ID, without expanding filesystem includes; missing summaries are counted in catalog.json. API generation cannot replace authored tutorials or invent explanations for undocumented members.
Generate a bundle
Build Release, then run from the checkout root:
dotnet run --project tools/Fabricators.Documentation.Tool -c Release --no-build -- . docs/documentation.json artifacts/documentation/0.19.0The destination must be new. The exporter validates all content first, writes a staging directory, then publishes the complete directory with a rename. It never overwrites an existing destination. The same command works on Windows, Linux and macOS with the pinned .NET SDK.
Frontend contract
| Artifact | Purpose |
|---|---|
| catalog.json | Schema version, product/version/channel/locale, ordered groups, page metadata, routes, source paths, hashes and heading anchors |
| pages/*.md | Versioned content with resolved documentation links and source examples |
| api.json | Stable compiler documentation IDs, kinds, signatures, summaries, parameter descriptions and return descriptions |
| search.json | Title, summary, keywords and page text tied to canonical routes |
| examples.json | Source code, language, verification label, provenance and hash |
| manifest.schema.json | Machine-readable input contract for authoring tooling |
| catalog/api/search/examples.schema.json | Machine-readable output contracts for renderer/client tooling |
| llms.txt | Compact discovery index for developer agents |
Treat the catalog's anchors as authoritative. The renderer must produce these exact IDs, including duplicate-heading suffixes. Use the page route for navigation and Content for the corresponding artifact fetch. The hash covers normalized UTF-8 Markdown without a BOM. Search and API references share the bundle version.
Rendering and trust
No UI, HTML site, CSS or JavaScript is generated. The frontend owns layout, code highlighting, responsive navigation, accessible search and visual quality. Disable raw HTML/active Markdown and sanitize rendered output and URLs; Markdown is data, not executable MDX. Do not infer safe rendering from content validation alone.
All current content is reviewed developer documentation. This static public bundle is not a tenant authorization system. A future restricted ERP documentation endpoint must filter pages, navigation, search, API metadata and agent indexes server-side, and partition caches by authority. Hiding a sidebar entry is insufficient.
Editorial structure
Cloudflare is the primary information-architecture reference, together with Stripe and rfw: entry points by goal, separate tutorials/concepts/how-to/reference, clear prerequisites, examples, configuration, limitations, troubleshooting and next steps. Plain Markdown is the initial portable format. Rich tabs, callouts and interactive API explorers require a later versioned renderer contract, not arbitrary components embedded by third-party authors.
Extension boundaries
OpenAPI already comes from the host's Swashbuckle integration. Importing OpenAPI, generating SDK-language variants, restricted ERP app composition and replacing the developer MCP's embedded catalog are tracked next steps, not implemented exports.
Public portal publication
The public documentation is published with docsp at docs.fabricators.dev. Authored Markdown remains in this repository; the versioned export supplies the same guides and compiler-derived API reference to the shared portal.
A release is not documentation-complete until the corresponding docsp project has been imported, checked, built and deployed. Initially this is a manual Wrangler deployment from the docs-portal repository; CI automation is a separate follow-up. Preserve previous documentation versions and other portal projects. Never publish private runtime configuration, tokens or generated logs.
The consumer integration and deployment commands are documented in
docs-portal/portals/fabricators/README.md. Generated content is verified against
its catalog SHA-256 values before import. Keep the original catalog/API JSON
available as versioned downloads for tooling clients.