Pinnate Docs

GitHubApp

Navigation

Sections, folders, groups, discovery, and public URLs.

Navigation has two layers:

  1. Top nav — from sections: in site.yaml (or the console)

  2. Sidebar — for guide sections, from the Markdown tree (folders + pages)

Top navigation

Each sections: entry becomes a top-nav item. Parents with children: become a dropdown label (no URL of their own).

sections:
  - name: Guide
    slug: guide
    path: .
  - name: API
    slug: api
    api: payments
  - name: More
    children:
      - name: SDKs
        slug: sdks
        sdk: payments-sdk
      - name: CLI
        slug: cli
        cli: payments-cli

URL shapes

Kind

Typical URL

Guide section home

/{sectionSlug}

Guide page

/{sectionSlug}/{pageSlug}

Nested guide page

/{sectionSlug}/{folder}/{page}

Embed section

/{sectionSlug} (+ nested resource routes as generated)

pageSlug may contain / when the file lives in a subdirectory (path-based slugs).

For a guide with path: guides (or .):

  1. Discover .md / .mdx under that path

  2. Apply site + section exclude globs

  3. Create folder nodes from directories (headline-cased labels)

  4. Sort pages (see Page settings)

  5. Seed the section menu from the page tree

Folders are structural (sidebar groups). They are not separate published “folder pages” in the prev/next sense—only real pages participate in page navigation.

Discovery vs explicit pages:

Prefer discovery so adding a file is enough:

- name: Guide
  slug: guide
  path: .

Use pages: when order must be pinned and position is not enough:

- name: Guide
  slug: guide
  path: .
  pages:
    - introduction.md
    - get-started/quickstart.md
    - get-started/concepts.md

Listed files are resolved relative to path. Missing files fail the sync.

Groups

Groups keep the top nav compact:

- name: More
  children:
    - name: SDKs
      slug: sdks
      sdk: payments-sdk

Only children are real sections. The parent label is not a route.

Icons

Guide pages can set icon in frontmatter (emoji, short text, or a Lucide name: book, book-open, box, code, file, file-text, globe, key, settings, shield, terminal, users). Page description is still used for SEO and search — it is not shown in the sidebar.

---
title: API keys
description: Create and rotate automation credentials.
icon: key
---

Tabs

Top-level tabs are the section bar from sections: in site.yaml. Each tab has its own sidebar. Optional icon on a section appears in the header.

Doc versions

A documentation version dropdown lists recent publishes (?v= for historical snapshots). For API document history, use registry versions.

Multiple product areas on one site are modeled with sections and groups (see above) — not a separate product switcher.