A Codocation project is plain files: YAML configuration, locale-owned Markdown, and explicit asset and definition namespaces. Everything is readable, diffable, and belongs in version control.

codocation.yml            project configuration
error-registry.yml        project-wide diagnostic severity overrides
assets/
  media/                  non-localized browser/chrome media, including the favicon
  fonts/                  global font binaries
  css/                    global site CSS
  js/                     global site JavaScript and analytics
definitions/               invariant definition IDs and fields
library/
  snippets/               reusable Markdown, always read and never published
  code/                   code files a fence includes with src=, never published
content/                    authored and published content root
  <locale>/                 a catalog locale, such as en/
    <site id>.tree.yml       required for each declared site membership
    <site id>.pdf.yml        optional locale PDF overrides
    <site id>.seo.yml        optional locale SEO overrides
    <site id>.redirects.yml  optional locale redirects
    site-strings.yml         this locale's built-in chrome text
    pages/                   the locale's Markdown pages
      index.md
      getting-started.md
      posts/                 blog posts, when the site is a blog
    images/                  locale-owned page, branding, and PDF images
    attachments/             locale-owned downloadable files
    definitions/             translated definition payloads

library/ is project-global and never published: snippets/ holds reusable Markdown whose IDs are unique across the whole project, and code/ holds the files a fence pulls in with {src="…" lines="…"} (see Markdown Extensions). site-strings.yml is locale-owned rather than per site, and carries the text Codocation itself writes into a page - the footnotes heading, the empty-listing line, and the rest; a missing file or a missing key is a warning with a fix that writes it.

The root definitions/ directory includes keyed labels.yml and categories.yml files. Their locale-owned counterparts contain localized names, optional label compact text, and tooltips. Each locale may omit an identity (unavailable), provide a local entry, or contain the explicit inherited: true entry to use the complete payload from the current site's effective defaultLocale. inherited: true must be that entry's only field: it takes the whole payload or none of it, and cannot be combined with local ones. Optional fields omitted from a local entry remain absent in that locale, and omission never triggers automatic fallback.

codocation.yml

The single technical project configuration file: site ids and types, URL and web settings, build output settings, the canonical locale catalog, each site's published locale membership and defaultLocale, and the deploy target. Reader-facing title and description, localized PDF text, SEO meta tags, and redirects live in each declared pair's files.

The navigation tree

content/<locale>/<site id>.tree.yml owns the required site title, optional description, and what that locale's site shows and in what order: the header links, the table of contents (with nested sections and the home-page marker), and the footer links. Each declared site membership has an independent tree; there is no implicit merge between locales. The "Codocation" tool window edits it visually; see Navigation.

Pages

Markdown files under content/<locale>/pages/, each with a small frontmatter block. A page not referenced by any tree is simply not published. Blog posts live under content/<locale>/pages/posts/.

The physical file content/en/pages/guide.md is referenced by its logical tree path pages/guide.md; the physical content/<locale>/ prefix is never part of a tree reference. The catalog locales themselves are listed under locales:; each site's published variants are listed under sites.<siteId>.locales in codocation.yml.

Images, attachments, and assets

content/<locale>/images/ holds locale-owned pictures referenced from pages, along with locale-aware branding and PDF images. content/<locale>/attachments/ holds downloadable files linked from pages. The favicon is non-localized at assets/media/; fonts, CSS, JavaScript, and analytics are global under their corresponding assets/ subspaces. A build copies resolved resources into the matching output directory; see Build the Site. Images and attachments follow the page's source provenance: a page resolved from the default language and displayed in another uses the source locale's media first, then its permitted fallback.

Definitions

Root definitions/ stores stable IDs and invariant fields. Locale-owned content/<locale>/definitions/ stores translated payloads. A locale uses the current site's effective defaultLocale for supported fallback. Labels and categories require an explicit inherited: true entry; an omitted classifier identity is unavailable. Variables, glossary terms, and keymaps may use a missing entry from the site default. They are edited in the "Definitions" and "Catalog" tool windows; see Variables and Definitions.