The platform topic covers the foundational infrastructure that supports the theme: project structure, file ownership boundaries, the validation pipeline, deployment operations, and build-time processing. These docs describe how the system is organized and how it enforces correctness — the machinery that implementors and developers interact with when building, validating, and shipping changes.
Who this is for
- Implementors — understanding the project structure, file ownership model, and validation pipeline so you can work confidently within the framework’s boundaries.
- Developers — extending the theme’s build pipeline, adding validation rules, modifying deployment procedures, or troubleshooting infrastructure-level issues.
- AI agents — generating code that respects ownership boundaries, passes validation gates, and follows the project’s directory conventions.
Key concepts
- File ownership — every source file is either CORE-OWNED (theme framework) or SITE-OWNED (per-site customization). This boundary governs what can be changed during theme upgrades versus what is preserved per-site.
- Validation pipeline — a multi-stage quality gate (
npm run validate) that checks formatting, linting, types, accessibility, and build output. All changes must pass before shipping. - Directory structure — the
src/tree follows a split-concern layout wheresrc/core/holds theme framework code andsrc/site/holds per-site customization. Content lives insrc/content/. - Static rules — custom lint rules that enforce project-specific invariants beyond what standard linters catch, validated at build time.
In This Topic
- Build & Request Pipeline — Request middleware (trailing-slash redirect) and build-time rehype plugins (internal link rewriting) — the two pipeline layers that transform requests and content.
- Architecture — Cross-cutting technical architecture — rendering strategy, JavaScript usage, accessibility standards, and progressive enhancement principles.
- Deployment Guide — Operational runbook for production deployment and redeployment after core sync.
- Directory Structure — Annotated project directory tree — what goes where, file ownership zones, and naming conventions.
- Docs Kit — Guide to the shared documentation system — what it provides, how child sites use the seed collection, and how to customize, extend, or remove it.
- File Ownership Model — Reference for the three-zone ownership model — how src/ is organized, what core owns vs. site owns, sync behavior, component overrides, and governance rules.
- Release Operations — Gate checklist for cutting a core theme release and rollback playbook for reverting a bad release.
- Static Rules Validation — Reference for the lint:static-rules framework — pluggable build-time source analysis with configurable rules, severity levels, and an inline + manifest exception system.
- Validation Pipeline — Reference for the npm run validate quality gate — command sequence, per-step specification, accessibility gate, performance budgets, and exception process.
- Validation Troubleshooting — How to diagnose and fix common validation pipeline failures — format, lint, type check, build, and accessibility gate errors.