Project structure — Sambadocs Docs

sambadocsDocs

A Sambadocs project is just a GitHub repository. One config file — docs.json at the repo root — tells Sambadocs what your site is called and how the pages are organized. Everything else is .mdx content.

docs.json

docs.json lives at the root of your repo. The two fields you'll always set are name and navigation:

{
  "name": "Acme Docs",
  "navigation": [
    {
      "group": "Getting started",
      "pages": ["introduction", "quickstart"]
    },
    {
      "group": "Guides",
      "pages": ["guides/authentication", "guides/webhooks"]
    }
  ]
}

name — your site's title.
navigation — an array of groups. Each group has a group label and a list of pages. Each page is the path to an .mdx file (without the extension), relative to the repo root.

Organizing pages

Pages can live anywhere in the repo; the path in pages points at them. A page can also override its URL with an explicit slug, and groups can nest:

{
  "group": "API",
  "pages": [
    { "page": "api/intro", "slug": "overview" },
    {
      "group": "Endpoints",
      "pages": ["api/users", "api/orders"]
    }
  ]
}

Tabs for larger sites

Bigger docs can split the top level into tabs (e.g. “Guides” and “API Reference”) using a tabs array instead of a flat navigation list. Start flat — add tabs when you actually need them.

OpenAPI

Point openapi at a spec file in your repo and Sambadocs generates a full API reference from it automatically:

{
  "name": "Acme Docs",
  "navigation": [{ "group": "Guides", "pages": ["introduction"] }],
  "openapi": "openapi.yaml"
}

See API reference from OpenAPI for details.

Redirects

When you rename or move a page, keep old links working with redirects:

{
  "redirects": [{ "from": "/old-intro", "to": "/introduction" }]
}

Writing pages — the MDX and frontmatter for a page.
Components — callouts, tabs, and code blocks.

docs.json

Organizing pages

OpenAPI

Redirects

Next