# Documentation publication The library repository owns documentation and executable examples. The website repository owns presentation, navigation UI, search, and the deployment artifact. Both render the same Markdown; do not maintain a second reference in website HTML. See the [editorial guide](../docs/maintainers/documentation.md) for content decisions. Use the [release checklist](../docs/maintainers/release-checklist.md) when publishing a new version; importing reference docs does not update the playground runtime or deploy the website and MCP. ## Build and review ```sh npm run docs:check npm run docs:export ``` `navigation.json` lists every current top-level guide, its title, section, and website route. `docs:check` verifies coverage, exact exported bytes, example marker ownership, generated HTML links, and anchors. Marker validation does not execute examples: use `npm run test:fixtures` or the relevant documented fixture command for behavioral evidence. `docs:export` writes `.docs-export/manifest.json` and exact Markdown files at their repository paths. `resources.json` explicitly lists supporting files: the diagnostic catalog, executable fixtures, portable agent skill, and saved trial evidence. Each is exported at its repository path as a hashed asset; the exporter does not recursively copy the repository. The manifest identifies package version, source revision, working changes, each file's SHA-256, and the combined content hash. No timestamps or network reads affect the export. A changed document requires a new import into the website. In the website checkout, import explicitly: ```sh npm run docs:import -- /absolute/path/to/.docs-export npm run check ``` The website vendors the snapshot and builds independently. Its build must reject missing or altered files and invalid routes. It must display working changes as such: an exported local edit is not a published release, even if its package version is unchanged. Consumer instructions and references also ship under `dist/docs/` in the npm package, generated by `npm run build`. They are not imported by the runtime. Package docs include the consumer fixtures and portable skill; maintainer guides and `benchmarks/docs/` evidence stay in the repository/site export. Older release documentation belongs to the `backbone.marionette` repository. For a release snapshot, export from a clean checkout of the exact release commit. Preserve that snapshot with the website revision that imported it. Do not label moving `master` content as stable or substitute the latest npm alpha for a source snapshot. The homepage's pinned demonstration has its own explicit provenance; updating reference docs does not silently update its runtime. ## Website integration The integrated prototype renders the full reference under `/docs/`, with local Pagefind search, Markdown alternatives, a scoped `llms.txt`, and links to exact source provenance. The existing website's layout and static builder remain the presentation layer. A framework migration is not required to obtain those features. The library's `.docs-site/` renderer remains a validation surface and the existing diagnostic-host artifact. It now uses the same complete navigation list rather than a separate publication allowlist. It maps `/docs/` entries to `/development/`. ## Hosting and distribution choices The default recommendation is Cloudflare Pages for the integrated static website. Keep GitHub as the canonical source and package distribution, and use Context7 as an optional retrieval channel. A docs-specific hosting service is an alternative when its managed version navigation is worth adapting the existing site. | Service | Role and current free boundary | Decision for Marionette | | --- | --- | --- | | Cloudflare Pages | Static asset requests are free and unlimited when they do not invoke Functions. The free plan permits 500 builds/month, 20,000 files/site, and 25 MiB/file. | Preferred host for the combined website and docs under the popularity constraint. Build once per reviewed content change; serve static files. | | GitHub Pages | Public repositories can use GitHub Free. Published sites have a 1 GB limit and a soft 100 GB/month bandwidth limit; rate limiting can apply. | Suitable for a small site or recovery copy, but less suitable as the primary host if traffic grows dramatically. | | Read the Docs Community | Free for open-source projects with public docs and advertising-supported hosting. | A credible managed-docs alternative if the project accepts its advertising and platform integration. Keep canonical Markdown in this repository if adopted. | | Context7 | Optional public-repository indexing and retrieval; consumers use their own accounts and quotas. | Add discovery without making the website depend on its API or availability. It does not replace the website host. | These are current plan boundaries, not promises that a provider will retain the same terms indefinitely. Recheck them before enabling a service. Do not attach a paid plan, enable usage overages, or add an automatic upgrade to compensate for traffic. If the free service is unavailable, retain downloadable package docs and the repository; consider another free static host instead of silently incurring a bill. Do not maintain a second independently authored documentation set. Sources checked September 2026: [Cloudflare static pricing](https://developers.cloudflare.com/pages/functions/pricing/), [Cloudflare platform limits](https://developers.cloudflare.com/pages/platform/limits/), [GitHub Pages limits](https://docs.github.com/en/pages/getting-started-with-github-pages/github-pages-limits), and [Read the Docs platform choices](https://about.readthedocs.com/choosing-a-platform/). ## Deployment decision The public website and optional documentation MCP have separate manual deployments. Prepare and review the complete static website artifact and matching MCP corpus, then follow the [website deployment runbook](https://github.com/marionettejs/marionettejs.com/blob/main/mcp/DEPLOYMENT.md) for the authorized hosting configuration and live checks. Keep static and installed documentation available independently of MCP. Record the previous deployments so content and presentation can be restored together if needed. Keep hosting within the authorized free plans; do not enable paid overages or an automatic upgrade. Record measured MCP CPU limits and accepted availability limitations for each release. A successful request does not prove the service stays within its provider's nominal resource budget. Domain registration remains an existing separate cost. The catalog reserves `/errors//` routes, and `docs-site/CNAME` configures `docs.marionettejs.com` for the diagnostic artifact. Runtime `MarionetteError.url` still uses the legacy `http://marionettejs.com/docs/v/` prefix and its per-error prose path; it does not yet point to the catalog route. Treat any runtime URL change as a separate reviewed contract change. The integrated website generates catalog pages from the same source. Before launch, configure the diagnostic domain to serve those routes, or deploy the library diagnostic artifact there. Do not remove published error codes or leave their URLs unresolved. Once that domain is served by the integrated artifact, retire the separate Pages deployment workflow and library presentation scaffold; keep the shared catalog and export validation. The existing `DOCS_PAGES_ENABLED` gate is not changed by this work. Legacy documentation at `marionettejs.com/docs/current/` describes earlier releases. Do not replace it implicitly when deploying the v5 preview. Stable and immutable release URLs require actual release snapshots and a separately reviewed route map. ## Context7 `context7.json` selects current consumer documentation and excludes maintainer policy and migration comparisons from default retrieval. Migration guides remain available through the canonical index; agents doing an upgrade should open those explicitly so old and new APIs retain their before/after context. The public library is `/marionettejs/marionette`; its development branch is `master`. A user should select documentation matching their actual installation or source revision. Keep parsing policy in this repository so changes can be reviewed alongside docs. Ownership verification requires the public proof file on the default branch; a local file alone does not claim the library. Refresh indexing after the reviewed configuration lands. Test representative retrieval for version confusion and integration choice before presenting Context7 as a reliable shortcut. For a release, follow the [Context7 steps in the release checklist](../docs/maintainers/release-checklist.md#5-close-the-release-or-recover): register the published version, request a refresh, and verify actual retrieval. Refreshing the configured development branch does not pin it to a release. Each developer connects Context7 using their own account. The docs site does not proxy queries or distribute a maintainer API key. Free-tier throttling may make Context7 unavailable; canonical Markdown, package documentation, and local website search remain usable. Do not enable a paid plan or usage overages. Sources checked September 2026: [Context7 configuration](https://context7.com/docs/library-owners), [Context7 ownership](https://context7.com/docs/howto/claiming-libraries), [Context7 plans](https://context7.com/plans), and [Cloudflare Pages pricing](https://developers.cloudflare.com/pages/functions/pricing/).