Site config

The sharpdocs.json + site.json files at the root of your docs folder.

A SharpDocs site is described by two files at the project root:

  • sharpdocs.json — structural. Locales, default locale, GitHub URL, artifacts path. Locale-free; never translated.
  • site.json — content. Title, description, sidebar. The default-locale version. Translatable via site.{locale}.json overlays — see Localization.

Both are loaded once at startup by ProjectRegistry.

sharpdocs.json (structural)

{
  "github":        "https://github.com/you/my-library",
  "artifacts":     "./artifacts",
  "defaultLocale": "en",
  "locales":       ["en", "vi"]
}
Field Purpose
github Optional repo URL. Rendered in the header.
artifacts Optional. Path to the nupkg folder; relative to this file.
defaultLocale Required. Where / redirects; the base sidebar's labels are this locale.
locales Required. Every locale the site ships, including the default.

Adding projects: [...] here switches the site to multi-project mode — see Multi-project sites. In multi-project mode the structural fields above move into each project's own sharpdocs.json; the root file just lists projects.

site.json (content base)

{
  "title":       "My library",
  "description": "A small library.",
  "sidebar": [
    {
      "label": "Fundamentals",
      "items": [
        { "label": "Site config", "slug": "fundamentals/site-config" },
        { "label": "Search",      "slug": "fundamentals/search" }
      ]
    }
  ]
}
Field Purpose
title Site title for this locale; shown in the header and <title>.
description Meta description.
sidebar Sidebar groups; each has a label and a list of items.

Each slug must match a markdown file under the project root. Slugs follow Markdown page rules.

Translating

To translate, copy site.json to site.{locale}.json and edit only the labels you want translated. Everything else inherits from the base. Same for pages: drop index.vi.md next to index.md. Full rules are in Localization.

Validation

At startup, ProjectRegistry validates that every sidebar slug resolves to a markdown file (base or locale override). A missing slug degrades that locale; if the default locale fails, the whole project degrades. In single-project mode a degraded-only-project means the site won't serve docs (the / redirect lands on a 404).

Pages that exist on disk but aren't in the sidebar are still reachable via direct URL — they just don't appear in nav.

A site with neither sidebar nor any .md files is valid: the locale runs with an empty sidebar.