Configure documentation navigation

Navigation comes from the content tree. Use .navigation.yml for folder structure and nested page frontmatter for shorter page labels; do not maintain a separate sidebar array.

Create a primary section

Mark the first folder in an area with sidebar: section:

title: Documentation
icon: lucide:book-open
sidebar: section

A section becomes a primary choice in the sidebar switcher. It contains its children and the following sibling groups until the next folder marked as a section.

Add flat groups

Use sidebar: group for a labeled set of pages inside the current section:

title: Concepts
icon: lucide:boxes
sidebar: group

title: Authoring
icon: lucide:pen-line
sidebar: group

Groups create headings, not another collapsible navigation level. Add an index.md file only when the folder needs a real landing page. Without an index page, the group remains structural and its child pages appear directly below the heading.

Shorten a page label

Keep the full page title useful in search results and set a shorter sidebar label under navigation:

---
title: Write documentation content
description: Structure Markdown pages for clear reading and predictable navigation.
navigation:
  title: Write content
  icon: lucide:file-pen-line
---

Use nested YAML. A dotted key such as navigation.title remains a literal field and does not change the generated label.

Choose the section control

The content tree defines the sections. App config changes only how readers switch between them:

export default defineAppConfig({
  ginkoDocs: {
    site: {
      docsSidebarSwitcher: "tabs",
    },
  },
});

Choose 'tabs', 'dropdown', or 'list'. The setting never creates, hides, or reorders content.