# Project Structure 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 / a catalog locale, such as en/ .tree.yml required for each declared site membership .pdf.yml optional locale PDF overrides .seo.yml optional locale SEO overrides .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](/writing/markdown-extensions/index.md)). `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//.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](/writing/navigation/index.md). ## Pages Markdown files under `content//pages/`, each with a small frontmatter block. A page not referenced by any tree is simply not published. Blog posts live under `content//pages/posts/`. The physical file `content/en/pages/guide.md` is referenced by its logical tree path `pages/guide.md`; the physical `content//` 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..locales` in `codocation.yml`. ## Images, attachments, and assets `content//images/` holds locale-owned pictures referenced from pages, along with locale-aware branding and PDF images. `content//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](/publishing/build-site/index.md). 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//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](/writing/variables/index.md) and [Definitions](/writing/definitions/index.md).