Multi-project setup

Host N libraries under one SharpDocs site, end to end.

This walks through standing up a multi-project site from scratch. If you already have a single-project site, the same steps apply — replace your root sharpdocs.json with the multi-project shape and add a per-project file alongside your existing markdown.

For the conceptual overview, see Multi-project sites.

1. Lay out the folders

The root sharpdocs.json lives at DocsRoot; each project lives wherever you point at, typically a sibling repo or sibling folder.

MyDocsHost/
  Program.cs
  appsettings.json
  site/
    sharpdocs.json        ← root config (multi-project)
codezerg-alpha/
  sharpdocs.json          ← per-project structural config
  site.json               ← per-project base content (title, sidebar)
  index.md
  guide.md
  artifacts/
    Codezerg.Alpha.1.0.0.nupkg
codezerg-beta/
  sharpdocs.json
  site.json
  index.md
  artifacts/
    Codezerg.Beta.0.1.0.nupkg

The project paths in the root config are resolved relative to the root docs folder, so ../codezerg-alpha works from site/.

2. Write the root sharpdocs.json

{
  "title": "Codezerg Libraries",
  "description": "Two libraries under one roof.",
  "projects": [
    { "id": "alpha", "path": "../codezerg-alpha" },
    { "id": "beta",  "path": "../codezerg-beta" }
  ]
}

The presence of projects is what flips the site into multi-project mode. The root file does not declare a sidebar — each project owns its own.

3. Write each per-project pair

codezerg-alpha/sharpdocs.json (structural):

{
  "github": "https://github.com/example/alpha",
  "artifacts": "./artifacts",
  "defaultLocale": "en",
  "locales": ["en"]
}

codezerg-alpha/site.json (base content):

{
  "title": "Alpha",
  "description": "First library.",
  "sidebar": [
    {
      "label": "Overview",
      "items": [
        { "label": "Introduction", "slug": "index" },
        { "label": "Guide",        "slug": "guide" }
      ]
    }
  ]
}

Repeat for codezerg-beta. artifacts is optional — it defaults to ./artifacts relative to the project. Each project owns its own defaultLocale / locales list, so Alpha can ship ["en"] and Beta can ship ["en", "ja"] independently. To translate, drop site.{locale}.json overlays alongside site.json — see Localization.

4. Configure the host

appsettings.json:

{
  "SharpDocs": {
    "DocsRoot": "site",
    "NavLinks": [
      { "Label": "Packages", "Href": "/packages" }
    ]
  }
}

ArtifactsRoot is ignored in multi-project mode — each project declares its own artifacts folder. Leaving it set is harmless, but it has no effect.

5. Run it

dotnet run

URLs you should hit:

  • / — landing page with one card per project
  • /docs/alpha — 302 to /docs/alpha/en (alpha's default locale)
  • /docs/alpha/en and /docs/alpha/en/guide — alpha's pages in EN
  • /docs/beta/en — beta's pages in EN
  • /docs/alpha/en/search?q=... — search scoped to alpha × EN
  • /v3/index.json — unified NuGet feed across both projects' artifacts (locale-free)
  • /packages — unified package browser (locale-free)

6. Verify

  • Each project should show as a card on / (no warning panel).
  • Sidebar links inside /docs/alpha/... should stay scoped to alpha.
  • /packages should list packages from both codezerg-alpha/artifacts and codezerg-beta/artifacts.
  • /api/manifest returns one entry per project — handy for spot-checking the registry.

If a card shows a warning panel, the project degraded at startup. See Troubleshooting.

What's next