Project structure
Where files go and which routes they produce.
acme-docs/
├── specistry.config.ts # trusted build code
├── openapi.yaml # optional contract
├── docs/ # authored pages (default ./docs)
│ ├── index.md # → /
│ ├── quickstart.mdx # → /docs/quickstart
│ ├── images/
│ │ └── first-email.gif
│ └── guides/
│ ├── index.md # → /docs/guides
│ └── webhooks.md # → /docs/guides/webhooks
├── changelog/
│ └── v2.json # authored release notes
└── .specistry/artifacts/ # build output — do not editRoute rules
- Segments are lowercase letters and digits joined by single hyphens, up to 80 characters
- At most four segments deep
indexnames the folder route- Only
.mdand.mdxare read; dotfiles andnode_modulesare ignored - Without
docs/index.*, the generated API reference is the homepage
Edge cases
Capitals or underscores in a file name
ROUTE_SLUG_INVALID✕ FAILSdocs/
docs/Getting_Started.md✓ FIXdocs/
docs/getting-started.mdFile names must already be route slugs.
Same route twice
ROUTE_COLLISION✕ FAILSdocs/
docs/setup.md
docs/setup.mdx✓ FIXdocs/
docs/setup.mdxBoth resolve to /docs/setup.
Symlink pointing outside docs
CONTENT_SOURCE_OUTSIDE_ROOT✕ FAILSdocs/
docs/shared.md -> ../../wiki/shared.md✓ FIXdocs/
# copy the file into docs/ insteadSources must stay under the docs directory.