Guide: Managing Navigation

PageGun supports declarative navigation trees for docs sites. Instead of tagging each page with nav fields, you define the entire sidebar structure in one place.

How It Works

Create a subroute (e.g. docs)
Set config.navigation with your nav tree
Pages are referenced by slug — titles are resolved automatically
Navigation is published to CDN on every page publish or subroute update

Three mutually-exclusive top-level modes:

The simplest option. Pages organized into collapsible groups.

{
  "navigation": {
    "groups": [
      {
        "group": "Getting Started",
        "pages": ["overview", "quickstart", "installation"]
      },
      {
        "group": "API Reference",
        "pages": [
          "api-overview",
          {
            "group": "Endpoints",
            "pages": ["create-page", "update-page", "delete-page"]
          }
        ]
      }
    ]
  }
}

Tabs (Horizontal Tab Bar)

Like Stripe Docs — a horizontal tab bar at the top, each tab has its own sidebar.

{
  "navigation": {
    "tabs": [
      {
        "tab": "Documentation",
        "icon": "book",
        "groups": [
          { "group": "Basics", "pages": ["overview", "quickstart"] }
        ]
      },
      {
        "tab": "API Reference",
        "icon": "code",
        "groups": [
          { "group": "Endpoints", "pages": ["pages", "projects"] }
        ]
      }
    ]
  }
}

Like Resend — icons at the top of the sidebar that switch between sections.

{
  "navigation": {
    "anchors": [
      {
        "anchor": "Documentation",
        "icon": "book",
        "groups": [
          { "group": "Guides", "pages": ["overview", "quickstart"] }
        ]
      },
      {
        "anchor": "Discord",
        "icon": "chat",
        "href": "https://discord.gg/your-server"
      }
    ]
  }
}

Page Entry Types

Each entry in the pages array can be one of three types:

String (Plain Slug)

"quickstart"

NavPage Object (Slug with Method Badge)

For API docs — shows colored HTTP method badges in the sidebar:

{"slug": "api-reference/pages/list", "method": "GET"}

NavGroup Object (Nested Group)

{"group": "Pages", "root": "api-reference/pages", "pages": [...]}

Method Badges

Add HTTP method badges to API endpoint pages in the sidebar. Supported methods:

Method	Color
`GET`	Green
`POST`	Orange
`PUT`	Blue
`PATCH`	Yellow
`DELETE`	Red

Example with a full API reference structure:

{
  "group": "Pages",
  "root": "api-reference/pages",
  "pages": [
    {"slug": "api-reference/pages/list", "method": "GET"},
    {"slug": "api-reference/pages/get", "method": "GET"},
    {"slug": "api-reference/pages/create", "method": "POST"},
    {"slug": "api-reference/pages/update", "method": "PUT"},
    {"slug": "api-reference/pages/publish", "method": "POST"},
    {"slug": "api-reference/pages/unpublish", "method": "POST"}
  ]
}

curl -X POST "https://api.pagegun.com/subroutes?project_id=YOUR_PROJECT" \
  -H "Authorization: Bearer $PAGEGUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"slug": "docs", "name": "Documentation", "navigation": {"groups": [{"group": "Getting Started", "pages": ["overview", "quickstart"]}]}}'

curl -X PUT "https://api.pagegun.com/subroutes/docs?project_id=YOUR_PROJECT" \
  -H "Authorization: Bearer $PAGEGUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"navigation": {"groups": [{"group": "Getting Started", "pages": ["overview", "quickstart"]}, {"group": "Advanced", "pages": ["custom-themes", "plugins"]}]}}'

Updating navigation automatically re-publishes the sidebar to CDN.

Group Options

Each group supports:

Field	Type	Description
`group`	string	Group title displayed in sidebar
`icon`	string	Icon name (optional)
`root`	string	Page slug to open when clicking group title
`expanded`	boolean	Default expanded state (for nested groups)
`pages`	array	Page slugs, NavPage objects, or nested groups

Nesting

Groups can be nested for sub-sections:

{
  "group": "API Reference",
  "pages": [
    "api-overview",
    {
      "group": "Pages",
      "root": "api-reference/pages",
      "pages": [
        {"slug": "create-page", "method": "POST"},
        {"slug": "get-page", "method": "GET"},
        {"slug": "list-pages", "method": "GET"}
      ]
    },
    {
      "group": "Projects",
      "pages": ["get-project", "list-projects"]
    }
  ]
}

Page Ordering

Pages appear in the sidebar in the order they are listed in the pages array. To reorder, simply rearrange the array and update the subroute.

Pages not referenced in the navigation tree are still accessible by URL — they just won't appear in the sidebar. This is useful for draft or unlisted pages.

Internationalization

Navigation is generated per-locale. Page titles are resolved from the locale-specific published version. CDN files follow the pattern:

nav.enc — default
nav.en.enc — English
nav.zh.enc — Chinese

The frontend automatically tries the locale-specific nav first, then falls back to the default.

Managing Navigation

How It Works

Navigation Modes

Groups (Simple Sidebar)

Tabs (Horizontal Tab Bar)

Anchors (Sidebar Icons)

Page Entry Types

String (Plain Slug)

NavPage Object (Slug with Method Badge)

NavGroup Object (Nested Group)

Method Badges

Setting Navigation via API

Create a Subroute with Navigation

Update Navigation

Group Options

Nesting

Page Ordering

Pages Not in Navigation

Internationalization