Navigation

Navigation is the only required field in sourcey.config.ts. It defines the tab structure, sidebar groups, and page ordering.

TabConfig

interface TabConfig {
  tab: string; // display name (required)
  slug?: string; // URL slug (defaults to slugified tab name)
  source: SourceAdapter; // created with markdown(), mkdocs(), openapi(), mcp(), doxygen(), or godoc()
}

Each tab must have exactly one content source. Sourcey 3.6 uses source: adapter(...) as the primary shape. Legacy direct fields (groups, mkdocs, openapi, mcp, doxygen, and godoc) still resolve for existing projects.

MkDocs source

Use mkdocs when a project already has a mkdocs.yml and you want Sourcey to render the same markdown source without rewriting the navigation by hand.

navigation: {
  tabs: [
    {
      tab: "Documentation",
      source: mkdocs("./mkdocs.yml"),
    },
  ],
}

Sourcey reads docs_dir (default docs) and imports nav / legacy pages. Top-level MkDocs nav sections become sidebar groups. Nested sections are flattened into labels like Guide / Install; explicit page labels are preserved. Local .md and .mdx pages are supported. External nav entries are ignored.

GroupConfig

interface GroupConfig {
  group: string; // sidebar section header (required)
  pages: string[]; // page slugs (required)
}

Pages are listed by slug (filename without extension). Sourcey resolves "quickstart" to quickstart.md or quickstart.mdx in the config directory.

Slug resolution

Glob patterns

Page arrays support trailing glob patterns for automatic file discovery:

source: markdown({
  groups: [
    {
      group: "API Guides",
      pages: ["api-*"],
      // Matches: api-auth.md, api-errors.md, api-pagination.md
    },
  ],
});

Matched files are sorted alphabetically. Use explicit page lists when order matters.

Page ordering

Pages appear in the sidebar in the order they're listed in the pages array. Groups appear in the order they're defined in the groups array. Tabs appear in the order they're defined in the tabs array.

There's no implicit ordering. The config is the source of truth for navigation structure.