{
  "id": "configuration",
  "title": "Site configuration",
  "description": "Configure branding, the repository link, an automatically detected SVG, PNG, or JPEG logo, layered navigation, colors, output, and interface language in site.config.json.",
  "type": "reference",
  "status": "observed",
  "visibility": "public",
  "tags": [
    "configuration",
    "branding",
    "navigation",
    "json"
  ],
  "related": [
    "home",
    "getting-started",
    "content-model"
  ],
  "sourceRefs": [
    "../../core/build.mjs",
    "site.config.json"
  ],
  "authors": [],
  "updated": null,
  "diagram": null,
  "body": "## Configure the publication\n\nEvery site owns a `site.config.json`. It contains publication choices; Aurelius supplies the runtime and layout.\n\n```json\n{\n  \"siteTitle\": \"Product handbook\",\n  \"siteDescription\": \"Reference for people and agents.\",\n  \"language\": \"en\",\n  \"outputDirectory\": \"dist\",\n  \"brand\": {\n    \"title\": \"Acme Docs\",\n    \"kicker\": \"product knowledge\",\n    \"name\": \"Acme\",\n    \"logoSource\": \"assets/acme.svg\",\n    \"logoAlt\": \"Acme logo\"\n  },\n  \"repository\": {\n    \"url\": \"https://github.com/acme/product-docs\"\n  },\n  \"navigation\": {\n    \"primary\": [\"home\", \"getting-started\", \"publishing\"],\n    \"sections\": [\n      { \"label\": \"Overview\", \"items\": [\"home\", \"getting-started\"] },\n      {\n        \"label\": \"Reference\",\n        \"items\": [\n          { \"label\": \"Authoring\", \"items\": [\"configuration\"] },\n          { \"label\": \"For agents\", \"items\": [\"agent-interface\"] }\n        ]\n      }\n    ]\n  },\n  \"colors\": {\n    \"paper\": \"#faf8f8\",\n    \"ink\": \"#2b2b2b\",\n    \"accent\": \"#84a59d\",\n    \"link\": \"#284b63\"\n  }\n}\n```\n\n## Expose the repository\n\n`repository.url` is optional. When it is configured, Aurelius adds a clearly labeled external link to the site header so readers can reach the repository that owns the documentation. Use a complete public `https://` URL:\n\n```json\n{\n  \"repository\": {\n    \"url\": \"https://github.com/acme/product-docs\"\n  }\n}\n```\n\nSet `repository` to `null` or omit it when the documentation should not expose a repository link.\n\n## Use your own logo\n\nWhen `init` runs without `--logo`, it searches the directory where you ran the command for `logo.svg`, `logo.png`, `logo.jpeg`, then `logo.jpg`, without treating letter case as significant. It copies the first match into the new site's `assets/` directory. If there is no match, Aurelius creates a small editable SVG placeholder.\n\nPass a local SVG, PNG, JPEG, or JPG to select a different file explicitly:\n\n```bash\nnpx --no-install aurelius init docs --title \"Acme Docs\" --logo ./brand/acme.svg\n```\n\nAurelius copies it into `docs/assets/` and writes `brand.logoSource`. You can later replace the asset or point the setting at another supported image. SVG is recommended for sharp rendering at any size; PNG and JPEG are useful when the visual identity contains raster artwork. Always provide meaningful `logoAlt` text.\n\n## Translate the interface, not your Markdown\n\n`language` controls all built-in reader-interface copy: search, buttons, metadata labels, diagram controls, feedback messages, and generated agent cards. It does not translate the Markdown you authored, so a site can keep English documents while its navigation and controls are in Portuguese:\n\n```json\n{ \"language\": \"pt-BR\" }\n```\n\nEnglish (`en`) is the default for a new site. Use `{ \"language\": \"pt-BR\" }` for the Portuguese interface. Editorial strings that you explicitly configure — such as `navigation.sections[].label`, `brand.title`, and footer text — remain yours to write in the desired language.\n\n## Keep global and local navigation separate\n\n`navigation.primary` feeds the compact top navbar and should contain only a few high-frequency destinations. `navigation.sections` feeds the complete left sidebar and scales to many documents. A section may contain a document ID or a folder object with `label` and nested `items`; folders can nest again when the information architecture warrants it. The right sidebar is page-local: it contains the table of contents, metadata, relationships, and machine-readable formats.\n\nOlder sites may still use a flat `navigation` array; Aurelius normalizes it for backward compatibility.\n\n## Important fields\n\n- `outputDirectory` is a dedicated subdirectory rebuilt from scratch by `build`. It cannot be the site root, `content/`, `diagrams/`, `assets/`, the configured runtime, or anything inside those source paths. Use `dist` unless there is a concrete deployment reason to change it.\n- `language` selects built-in interface copy. This example uses English; use `pt-BR` for Portuguese.\n- `repository.url` adds the external repository link to the site header; omit `repository` or set it to `null` to hide the link.\n- `colors` defines the light-theme tokens used by both screen and print.\n- `framework.runtime` is an advanced escape hatch for a customized runtime directory.\n\nKeep `brand.kicker` short. It identifies the knowledge surface; it should not compete with the page title.\n\nAurelius validates the values you actually declared before applying defaults. A malformed `navigation`, `repository`, brand, runtime, footer, or color object stops `check` with the field name instead of silently falling back to another value.",
  "sections": [
    {
      "id": "configure-the-publication",
      "level": 2,
      "title": "Configure the publication",
      "text": "Every site owns a `site.config.json`. It contains publication choices; Aurelius supplies the runtime and layout.",
      "line": 1
    },
    {
      "id": "expose-the-repository",
      "level": 2,
      "title": "Expose the repository",
      "text": "`repository.url` is optional. When it is configured, Aurelius adds a clearly labeled external link to the site header so readers can reach the repository that owns the documentation. Use a complete public `https://` URL:   Set `repository` to `null` or omit it when the documentation should not expose a repository link.",
      "line": 43
    },
    {
      "id": "use-your-own-logo",
      "level": 2,
      "title": "Use your own logo",
      "text": "When `init` runs without `--logo`, it searches the directory where you ran the command for `logo.svg`, `logo.png`, `logo.jpeg`, then `logo.jpg`, without treating letter case as significant. It copies the first match into the new site's `assets/` directory. If there is no match, Aurelius creates a small editable SVG placeholder.  Pass a local SVG, PNG, JPEG, or JPG to select a different file explicitly:   Aurelius copies it into `docs/assets/` and writes `brand.logoSource`. You can later replace the asset or point the setting at another supported image. SVG is recommended for sharp rendering at any size; PNG and JPEG are useful when the visual identity contains raster artwork. Always provide meaningful `logoAlt` text.",
      "line": 57
    },
    {
      "id": "translate-the-interface-not-your-markdown",
      "level": 2,
      "title": "Translate the interface, not your Markdown",
      "text": "`language` controls all built-in reader-interface copy: search, buttons, metadata labels, diagram controls, feedback messages, and generated agent cards. It does not translate the Markdown you authored, so a site can keep English documents while its navigation and controls are in Portuguese:   English (`en`) is the default for a new site. Use `{ \"language\": \"pt-BR\" }` for the Portuguese interface. Editorial strings that you explicitly configure — such as `navigation.sections[].label`, `brand.title`, and footer text — remain yours to write in the desired language.",
      "line": 69
    },
    {
      "id": "keep-global-and-local-navigation-separate",
      "level": 2,
      "title": "Keep global and local navigation separate",
      "text": "`navigation.primary` feeds the compact top navbar and should contain only a few high-frequency destinations. `navigation.sections` feeds the complete left sidebar and scales to many documents. A section may contain a document ID or a folder object with `label` and nested `items`; folders can nest again when the information architecture warrants it. The right sidebar is page-local: it contains the table of contents, metadata, relationships, and machine-readable formats.  Older sites may still use a flat `navigation` array; Aurelius normalizes it for backward compatibility.",
      "line": 79
    },
    {
      "id": "important-fields",
      "level": 2,
      "title": "Important fields",
      "text": "- `outputDirectory` is a dedicated subdirectory rebuilt from scratch by `build`. It cannot be the site root, `content/`, `diagrams/`, `assets/`, the configured runtime, or anything inside those source paths. Use `dist` unless there is a concrete deployment reason to change it. - `language` selects built-in interface copy. This example uses English; use `pt-BR` for Portuguese. - `repository.url` adds the external repository link to the site header; omit `repository` or set it to `null` to hide the link. - `colors` defines the light-theme tokens used by both screen and print. - `framework.runtime` is an advanced escape hatch for a customized runtime directory.  Keep `brand.kicker` short. It identifies the knowledge surface; it should not compete with the page title.  Aurelius validates the values you actually declared before applying defaults. A malformed `navigation`, `repository`, brand, runtime, footer, or color object stops `check` with the field name instead of silently falling back to another value.",
      "line": 85
    }
  ],
  "sourcePath": "content/configuration.md",
  "visuals": [],
  "apiVersion": 1
}