5.0.0-beta.2 · Published beta · 13f4954c. Published on npm. Match your installed version.
MaintainersDocumentation 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 for content decisions. Use the release checklist when publishing a new version; importing reference docs does not update the playground runtime or deploy the website and MCP.
Build and review#
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:
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, Cloudflare platform limits, GitHub Pages limits, and Read the Docs platform choices.
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 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/<code>/ 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<version>/ 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: 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, Context7 ownership, Context7 plans, and Cloudflare Pages pricing.