sharpdocs.json schema

The full shape of the site config file, single- and multi-project.

sharpdocs.json lives at the root of DocsRoot and is required. The shape depends on the mode.

Path resolution rule: every relative path inside a sharpdocs.json is resolved relative to the directory of that file. The root sharpdocs.json's projects[].path is relative to the root docs folder; a per-project sharpdocs.json's artifacts is relative to its own project folder. Paths in appsettings.json follow a different rule (see Configuration options).

Single-project schema

{
  "title":       "string",          // site title
  "description": "string",          // meta description
  "github":      "string | null",   // optional repo URL, rendered in header

  "sidebar": [
    {
      "label": "string",            // group heading
      "items": [
        {
          "label": "string",        // link text
          "slug":  "string"         // must match a page slug
        }
      ]
    }
  ]
}

Multi-project schema (root)

When the root sharpdocs.json has a projects array, the site runs in multi-project mode. The root file becomes a thin pointer; each project keeps its own single-project-shaped sharpdocs.json at its referenced path.

{
  "title":       "string",
  "description": "string",
  "github":      "string | null",

  "projects": [
    {
      "id":   "string",   // url segment, sanitized to [a-z0-9-]
      "path": "string"    // relative to the root docs folder
    }
  ]
}

A root file with both sidebar and projects is valid — the sidebar is ignored when projects is non-empty.

Multi-project schema (per project)

Each project folder contains its own sharpdocs.json:

{
  "title":       "string",
  "description": "string",
  "github":      "string | null",
  "artifacts":   "string | null",   // optional, default "./artifacts", relative to project
  "sidebar":     [ /* same shape as single-project */ ]
}

Matching rules

  • JSON property names are case-insensitive.
  • slug is matched case-insensitively against the in-memory page lookup.
  • Leading and trailing slashes on slug are trimmed before lookup.
  • Project id is sanitized: lowercased, anything outside [a-z0-9-] stripped, runs of - collapsed, leading/trailing - trimmed.
  • Reserved project ids (post-sanitization): search, packages, v3, api, docs. A project using one of these is degraded with an error.
  • Duplicate project ids (post-sanitization) silently drop the second occurrence.

Validation at startup

  • The root file must exist — FileNotFoundException otherwise.
  • The root file must deserialize to a non-null object — InvalidOperationException otherwise.
  • Every sidebar slug must resolve to a markdown file. In single-project mode, a missing slug throws and is fatal. In multi-project mode it degrades just that project — the rest of the site still boots.
  • A missing or malformed per-project sharpdocs.json degrades the project, not the site.

Complete examples

Single-project

{
  "title": "My library",
  "description": "A small .NET library.",
  "github": "https://github.com/you/my-library",
  "sidebar": [
    {
      "label": "Overview",
      "items": [ { "label": "Introduction", "slug": "index" } ]
    }
  ]
}

Multi-project root

{
  "title": "Codezerg Libraries",
  "description": "Shared utilities.",
  "projects": [
    { "id": "alpha", "path": "../codezerg-alpha" },
    { "id": "beta",  "path": "../codezerg-beta" }
  ]
}

Multi-project per-project

{
  "title": "Alpha",
  "description": "First library.",
  "artifacts": "./artifacts",
  "sidebar": [
    { "label": "Start", "items": [ { "label": "Intro", "slug": "index" } ] }
  ]
}