Site Config

Bark draws from two separate configuration files, and understanding why helps you decide where a setting belongs.

1. Environment settings. Found in appsettings.json or your .env file is for deployment-level concerns: where your Markdown files live, whether hot-reload is on, and what base path the server sits at.
2. Site configuration. Found in docs/config.json lives alongside your content and controls everything your readers see, from the site name and navigation structure to the footer and social links.

That distinction means you can check config.json into the same repository as your docs and deploy the server without touching it.

If you are looking for a narrative walkthrough of these settings rather than a field-by-field reference, Configuration walks through the most common setups step by step.

appsettings.json: Docs ​

These settings apply at the host level and take effect at startup, so a restart is needed after changing them. If your deployment runs Bark in a container or through an orchestration platform, every field here can be provided as an environment variable instead. See Environment Variables for how the naming convention works.

appsettings.json: Docs:Themes ​

About Theming

There are two ways to apply your own theme, and they complement each other nicely. Dropping files into wwwroot/theme/ is the quickest path: a custom.css file there is loaded after Bark's built-in styles, a custom.js file is injected before the closing </body>, and a theme.json file accepts CSS variable overrides in a structured format. These are picked up at startup without any configuration changes, which works well when you can edit the filesystem directly.

If you would rather track theme settings in version control alongside the rest of your infrastructure, the Docs:Themes section of appsettings.json offers the same options. When Docs:Themes is present it takes full priority over theme.json, so the two are not merged.

See Extending Themes for a practical walkthrough of both approaches.

Configuration

Every field here is optional. Each one is either a CSS variable override or a theme feature toggle, and anything you leave unset simply falls back to Bark's default palette and behavior. The same fields, written in camelCase, are accepted in wwwroot/theme/theme.json if you prefer the filesystem approach.

docs/config.json: site metadata ​

These settings shape how your site presents itself to readers, search engines, and social platforms. For a deeper look at the HTML head fields specifically, see HTML Metadata.

HeadTag

docs/config.json: navigation ​

There are three navigation building blocks you can combine depending on the shape of your documentation. topNav populates the horizontal bar at the top of the page, which works well for top-level sections or external links. sidebar lets you define a different sidebar for each section by mapping path prefixes to nav trees; the longest matching prefix wins. nav is a simpler alternative that shows the same sidebar on every page, which suits smaller sites that do not need path-scoped sidebars. When both sidebar and nav are present, sidebar takes priority for any page whose path it matches.

TopNavItem

A TopNavItem is either a direct link (text + link) or a dropdown (text + items), but not both at the same time.

NavEntry

EditLinkConfig

PageControlsConfig

PageControlsEditLinkConfig

Full example, matching the structure used throughout this documentation site:

{
  "title": "Bark",
  "description": "A fast, lightweight Markdown documentation server built on .NET.",
  "lang": "en",
  "brand": "Bark",
  "brandImage": "/brand-image.svg",
  "footer": "Built with Bark · [AGPL-3.0](LICENSE)",
  "favicon": "🌳",
  "lastUpdated": true,
  "editLink": {
    "pattern": "https://github.com/melosso/bark/edit/main/docs/:path",
    "text": "Edit this page on GitHub"
  },
  "topNav": [
    { "text": "Home", "link": "/" },
    { "text": "Guide", "link": "/getting-started/getting-started" },
    { "text": "Reference", "link": "/reference/site-config" },
    {
      "text": "More",
      "items": [
        { "text": "GitHub", "link": "https://github.com/melosso/bark" },
        { "text": "Releases", "link": "https://github.com/melosso/bark/releases" }
      ]
    }
  ],
  "sidebar": {
    "/getting-started/": [
      {
        "title": "Introduction",
        "collapsed": false,
        "items": [
          { "title": "Getting Started", "path": "getting-started/getting-started" },
          { "title": "Configuration", "path": "getting-started/configuration" }
        ]
      }
    ],
    "/reference/": [
      {
        "title": "Reference",
        "items": [
          { "title": "Site Config", "path": "reference/site-config" },
          {
            "title": "Customisation",
            "items": [
              { "title": "Nav", "path": "reference/default-theme-nav" },
              { "title": "Sidebar", "path": "reference/default-theme-sidebar" }
            ]
          }
        ]
      }
    ]
  },
  "socialLinks": [
    { "icon": "github", "url": "https://github.com/melosso/bark", "title": "GitHub" },
    { "icon": "mastodon", "url": "https://fosstodon.org/@example", "title": "Mastodon" }
  ],
  "pageControls": {
    "downloadMarkdown": true,
    "subscribeRss": true,
    "editLink": {
      "label": "Edit on GitHub",
      "icon": "github"
    }
  }
}

docs/config.json: social links ​

Social links appear in the top-right area of the header on desktop and fold into the mobile sidebar on smaller screens. Each entry needs at minimum an icon name and a url.

CLI flags ​

When launching Bark directly from the terminal rather than through Docker or a process manager, a small set of flags let you adjust runtime behavior without editing config files. These are most commonly used during the static export workflow, but they work just as well against the live server.

What Bark does not configure ​

Bark keeps its configuration surface intentionally small. There are no build pipeline options, bundler settings, or lifecycle hooks, because Bark runs without a client-side build step.

Features like math rendering, syntax highlighting, and custom containers are part of the core and are always active.

If you find yourself needing custom asset pipelines or structural layout changes, the recommended approach is to fork the source and modify it directly. Feel free to contribute by opening an issue in our open source repository.