Design principles

Files are canonical

With the filesystem provider, authored files are the source of truth. Parsed caches, normalized documents, locale indexes, navigation, search records, sitemap entries, and prerender routes are derived and can be rebuilt.

An external provider takes the place of the filesystem as source of truth. It still returns source facts through the provider contract; Ginko applies the same public document and route model.

Every read belongs to a collection

Queries require a collection handle or name. The collection fixes the source, schema, route mount, locale behavior, sitemap policy, and provider boundary before a read runs. Exported handles also preserve schema inference in application code.

Routes are data, not guesses

Route-backed page documents carry route.resolvedPath, route.alternates, and resolution. Applications render those facts instead of rebuilding URLs from file paths, IDs, or locale conventions. Data-collection records have no public page route and should not be rendered as links.

Processing has one direction

1. Discover files or receive raw provider documents.
2. Parse and transform Markdown or structured data, including deterministic custom transforms and source-path metadata.
3. Expand locales into the document variants defined by the collection.
4. Validate each variant against the collection schema and JSON-safe document contract.
5. Project the validated documents into public query and route facts.
6. Consume the result in pages, queries, navigation, search, sitemaps, and agent-readable output.

All consumers use the normalized document. They do not independently reinterpret the source file.

Integrations keep their native responsibilities