Configuration

Configuration is split across two files:

• appsettings.json: host settings, which include: content root, hot reload, theme colors. Per deployment; applied on restart.
• docs/config.json: content settings, which include: title, metadata, brand, navigation, footer, social links. Per project; applied through hot reload.

Content settings do not require deployment access.

This page covers the common settings. Field reference: Site Config. Container variable names: Environment Variables.

Server settings ​

Defined in the Docs section of appsettings.json:

{
  "Docs": {
    "RootPath": "../../docs",
    "DefaultPage": "index",
    "EnableHotReload": true,
    "BasePath": "/your-repo"
  }
}

Colors, fonts, custom CSS and JavaScript: Themes.

Site settings ​

docs/config.json defines the site title, HTML metadata, navigation, footer and social links. Navigation is covered below; other fields: Site Config.

Navigation options (combinable):

1. Auto-generated. Without nav, sidebar or topNav, the sidebar is built from the folder structure.
2. Single sidebar (nav) for the whole site.
3. Header navigation with dropdowns (topNav) and per-section sidebars (sidebar, keyed by path prefix).

{
  "brand": "Bark",
  "topNav": [
    { "text": "Home", "link": "/" },
    { "text": "Guide", "link": "/guide/getting-started" },
    { "text": "Reference", "link": "/reference/site-config" },
    {
      "text": "More",
      "items": [
        { "text": "GitHub", "link": "https://github.com/hawkinslabdev/bark" },
        { "text": "Releases", "link": "https://github.com/hawkinslabdev/bark/releases" }
      ]
    }
  ],
  "sidebar": {
    "/guide/": [
      {
        "title": "Introduction",
        "items": [
          { "title": "Getting Started", "path": "guide/getting-started" },
          { "title": "Configuration", "path": "guide/configuration" },
          { "title": "Routing", "path": "guide/routing" },
          { "title": "Deploy", "path": "guide/deploy" }
        ]
      }
    ],
    "/reference/": [
      {
        "title": "Reference",
        "items": [
          { "title": "Site Config", "path": "reference/site-config" },
          { "title": "API Reference", "path": "reference/api-reference" },
          { "title": "Sitemap & Crawlers", "path": "reference/sitemap-generation" }
        ]
      }
    ]
  },
  "socialLinks": [
    { "icon": "github", "url": "https://github.com/hawkinslabdev/bark", "title": "GitHub" }
  ]
}

A topNav item is a link (text, link) or a dropdown (text, items).

sidebar keys are path prefixes; the longest match wins, so /guide/ and /guide/advanced/ can coexist.

footer is rendered as Markdown. Social link icon values "github" and "mastodon" render as inline SVG; other values render as text.

Translations ​

String tables are stored in docs/locale/. All interface text (search modal, table of contents heading, pager labels, ARIA labels, 404 page) comes from a string table. English is built in. locale selects a language file:

{
  "locale": "nl"
}

This loads docs/locale/nl.json. Object form: "locale": { "code": "nl" }. Without locale, lang is used, then English.

docs/locale/en.json lists every key and serves as the template:

{
  "searchPlaceholder": "Documentatie doorzoeken...",
  "tocTitle": "Op Deze Pagina",
  "pagerNext": "Volgende"
}

Rules:

• Missing keys fall back to English.
• Placeholders such as {0} must be kept as in the English source.
• Unknown keys are ignored and logged as a warning.
• Invalid JSON is skipped with a warning; the interface falls back to English.

Locale files apply through hot reload. They are not served over HTTP or listed by the API.

Bundled: en.json, nl.json. locale sets one interface language for the site; per-tree languages are configured under Translated pages.

Translated pages ​

Page translations use one directory per language, declared in config.json:

{
  "locales": {
    "root": { "label": "English", "lang": "en" },
    "nl": { "label": "Nederlands", "lang": "nl" }
  }
}

root is the untranslated tree at the top of docs/. Other keys are both directory name and locale code: docs/nl/guide/install.md is served at /nl/guide/install/ with strings from docs/locale/nl.json.

docs/
  index.md                  → /
  guide/install.md          → /guide/install/
  nl/
    index.md                → /nl/
    guide/install.md        → /nl/guide/install/

Each tree has its own navigation, search index and <html lang>. The header includes a language switcher (globe icon) when two or more languages are configured. A /nl/ sidebar key defines that tree's sidebar.

Pages with layout: home never render a translation notice.

Untranslated pages are served at the translated URL with the translated interface and a notice linking to the original. Their canonical points to the original, and they are excluded from that tree's search index.

When the original is newer than the translation (by timestamp), an outdated-translation notice is rendered.

Drafting a translation with LibreTranslate ​

A one-off generator drafts a translated tree through a self-hosted LibreTranslate instance. Output is regular Markdown for review and editing; there is no runtime translation.

dotnet run --project src/Bark -- --translate nl --translate-endpoint http://localhost:5000

Flags:

Not translated: fenced and indented code, inline code, link and image targets, HTML blocks, container markers, and front matter except title and description. Headings receive an explicit {#anchor} matching the original slug.

Generated files set machineTranslated: true, which renders a machine-translation notice. Remove the flag after human review.

Translating the menus ​

Text in config.json (menu labels, sidebar titles, brand, footer, promo bar, edit-link label) is written once. Translations are stored in the locale file as a dictionary keyed by the original text:

{
  "tocTitle": "Op Deze Pagina",
  "config": {
    "Getting Started": "Aan de slag",
    "Configuration": "Configuratie",
    "Edit this page on GitHub": "Bewerk deze pagina op GitHub",
    "Built with Bark.": "Gebouwd met Bark."
  }
}

Navigation structure is shared across languages; only labels are translated. Missing entries render in the original language.

Markdown values use the exact source string, including links, as the key:

"config": {
  "Built with Bark · [EUPL-1.2](/LICENSE).": "Gebouwd met Bark · [EUPL-1.2](/LICENSE)."
}

config is a reserved key in locale files. Other keys are interface strings; unknown keys are logged as a warning.

Versions ​

versions in config.json lists the documentation versions, newest first. A version is a separate deploy or a folder in docs/. The list format and separate deploys are described in Site Config.

A folder version is an entry whose link is one path segment with a matching folder: { "text": "v1.0", "link": "/v1.0/" } with docs/v1.0/. docs/v1.0/guide/install.md is served at /v1.0/guide/install/.

{
  "versions": {
    "items": [
      { "text": "v2.0", "link": "/" },
      {
        "text": "v1.0",
        "link": "/v1.0/",
        "sidebar": {
          "/guide/": [
            { "title": "Guide", "items": [{ "title": "Install", "path": "guide/install" }] }
          ]
        }
      }
    ]
  }
}

docs/
  index.md                  → /
  guide/install.md          → /guide/install/
  v1.0/
    index.md                → /v1.0/
    guide/install.md        → /v1.0/guide/install/

• Each folder version has its own navigation and search index. A version uses the language and interface strings of its tree.
• Absolute links in a version page, such as /guide/install, resolve inside the version folder.
• The switcher entry of a folder version links to the same page in that version. If the page does not exist in that version: the entry links to the version home. Entries without a folder link to the root of that deploy.
• Pages of an older version render a notice with a link to the latest version, are marked noindex, and are left out of the sitemap and feed.
• A page missing from a version returns 404. Versions do not fall back to pages of the latest version.

Version folders must differ from locale codes and the primary language code. If a version folder matches one: the folder is served as a version, and startup logs a warning.

Translated versions ​

A translated version is a version folder inside a locale folder. docs/nl/v1.0/guide/install.md is served at /nl/v1.0/guide/install/.

docs/
  v1.0/guide/install.md       → /v1.0/guide/install/
  nl/
    guide/install.md          → /nl/guide/install/
    v1.0/guide/install.md     → /nl/v1.0/guide/install/

• A translated version uses the language and interface strings of its locale, and the sidebar of its version.
• If a page is missing from a translated version: the page of the same version in the primary language is served with the untranslated notice. A page missing from both returns 404.
• The version switcher keeps the current locale. The locale switcher keeps the current version.
• Each translated version has its own search index.
• --translate translates version folders into the locale folder.