This repository keeps user-facing documentation separate from repository-maintenance material.
| Surface | Owns |
|---|---|
site/ |
Core-owned source for the user guide |
architecture.md |
Current cross-module composition and authority boundaries |
conformance.md |
Current JSON:API support status by feature and layer |
release.md |
Release/publication mechanics and dependency-baseline verification |
security.md |
Repository security signals, ownership, and vulnerability triage policy |
vision.md |
Stable product direction |
adr/ |
Consequential architectural rationale |
../CONTRIBUTING.md |
Contributor setup, verification commands, and dependency-verification maintenance |
../AGENTS.md |
Optional repository onboarding for agents |
| Javadoc | Public API contracts and semantics |
Do not add maintainer docs to site/ merely because MkDocs can render Markdown. Public pages should
answer a concrete library-user question; repository guidance remains in its canonical document.
Core owns the guide source and navigation under docs/site/.
jsonapi-docs owns shared MkDocs assembly,
validation, and GitHub Pages deployment, including portal-root discovery files.
See its README for preview and build instructions.
Core publishes immutable release documentation snapshots and append-only documentation revisions through the shared workflow. The release lifecycle owns publication mechanics; Core does not build or deploy a standalone site.
- Add or edit Markdown and assets below
docs/site/. - Add the page to
site/nav.yml, keepingindex.mdfirst. - Use relative links between site pages and check links and assets under
/core/<version>/.