---
title: Customize the navbar and footer
description: Add navigation links, a primary action, footer groups, and social links from docs.json.
url: https://docs.thally.io/guides/navbar-and-footer
---

# Customize the navbar and footer

Add navigation links, a primary action, footer groups, and social links from docs.json.

The top navigation bar and the footer are both configurable from `docs.json`. No code changes required — add a `navbar` or `footer` block and Thally picks it up automatically.

## Navbar

Add a `navbar` block to `docs.json` to control the links and CTA button in the top bar.

```json
"navbar": {
  "links": [
    { "label": "GitHub", "href": "https://github.com/your-org/repo", "type": "github" },
    { "label": "Support", "href": "https://support.example.com" }
  ],
  "primary": { "label": "Get started", "href": "/quickstart" }
}
```

### `navbar.links`

An array of navigation links rendered to the left of the CTA button.

| Field | Type | Description |
| --- | --- | --- |
| `label` | `string` | Link text |
| `href` | `string` | Destination URL (internal or external) |
| `type` | `"github"` _(optional)_ | Set to `"github"` to render the GitHub icon alongside the label |

When `type: "github"` is set, the GitHub mark is shown to the left of the label:

```json
{ "label": "GitHub", "href": "https://github.com/your-org/repo", "type": "github" }
```

External links open in a new tab automatically.

### `navbar.primary`

The primary CTA button — rendered as a filled accent pill in the top bar. When set, it overrides the auto-detected CTA from `siteConfig.links`.

```json
"primary": { "label": "Get started", "href": "/quickstart" }
```

Set `primary` to `null` to remove the CTA button entirely, even when `siteConfig.links` would normally supply one:

```json
"primary": null
```

> **Fallback:**
When `navbar` is not defined in `docs.json`, Thally falls back to auto-detecting a support link and CTA from `siteConfig.links` in `src/data/site.ts`. Define `navbar` in `docs.json` when you want explicit control.

### `navbar.logo`

Control the logo image and site name display in the top bar. These settings provide a source-controlled fallback when no managed or admin logo is configured.

```json
"navbar": {
  "logo": {
    "light": "/brand/logo-light.svg",
    "dark": "/brand/logo-dark.svg",
    "showTitle": true,
    "rightText": "Docs"
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `light` | `string` | Path to the light-mode logo asset |
| `dark` | `string` _(optional)_ | Path to a dark-mode variant. Falls back to `light` when omitted |
| `showTitle` | `boolean` _(optional)_ | Show the site name next to the logo. Defaults to `true`; set to `false` to hide the site name |
| `rightText` | `string` _(optional)_ | Secondary text shown after the site name |

When `logo` is omitted entirely, Thally shows the default logo image and appends a "Docs" suffix after the site name.

Logo paths must point to files inside `public/`. External URLs, path traversal, query strings, and backslashes are rejected. When a logo object is configured, the "Docs" suffix appears only if you supply `rightText`.

Set `logo` to `null` for a text-only wordmark that hides the logo image and the "Docs" suffix:

```json
"navbar": {
  "logo": null
}
```

---

## Footer

Add a `footer` block to `docs.json` to render a multi-column link grid and social icons at the bottom of every page.

```json
"footer": {
  "socials": {
    "github": "https://github.com/your-org",
    "twitter": "https://twitter.com/yourhandle",
    "discord": "https://discord.gg/invite"
  },
  "links": [
    {
      "heading": "Documentation",
      "items": [
        { "label": "Quick Start", "href": "/quickstart" },
        { "label": "Guides", "href": "/guides/getting-started" }
      ]
    },
    {
      "heading": "Tooling",
      "items": [
        { "label": "CLI Reference", "href": "/guides/cli-reference" },
        { "label": "MCP Server", "href": "/guides/mcp-server" }
      ]
    }
  ]
}
```

### `footer.socials`

A map of social platform keys to URLs. Supported keys with icons:

| Key | Icon |
| --- | --- |
| `github` | GitHub mark |
| `twitter` or `x` | X (Twitter) mark |
| `discord` | Discord logo |
| `linkedin` | LinkedIn logo |

Any other key renders as a plain text link.

### `footer.links`

An array of link columns. Each column has:

| Field | Type | Description |
| --- | --- | --- |
| `heading` | `string` | Column heading (rendered in small caps) |
| `items` | `Array<{ label, href }>` | Links in this column |

Columns are displayed in a responsive grid — 2 columns on mobile, 3 on tablet, 4 on desktop.

### `footer.copyright`

Override the default copyright line with a custom string. Use `{year}` as a placeholder for the current year:

```json
"footer": {
  "copyright": "Copyright {year} Acme Inc."
}
```

When omitted, the footer shows "© YYYY SiteName. All rights reserved." using the name from `siteConfig`.

> **Default footer:**
When `footer` is not defined in `docs.json`, Thally renders a minimal single-line footer with the site name and `siteConfig.links`.

---

## Full example

```json
{
  "navbar": {
    "links": [
      { "label": "GitHub", "href": "https://github.com/your-org/repo", "type": "github" }
    ],
    "primary": { "label": "Get started", "href": "/quickstart" },
    "logo": {
      "light": "/brand/logo-light.svg",
      "dark": "/brand/logo-dark.svg",
      "showTitle": true,
      "rightText": "Docs"
    }
  },
  "footer": {
    "copyright": "Copyright {year} Your Company.",
    "socials": {
      "github": "https://github.com/your-org",
      "twitter": "https://twitter.com/yourhandle"
    },
    "links": [
      {
        "heading": "Product",
        "items": [
          { "label": "Overview", "href": "/" },
          { "label": "Quick Start", "href": "/quickstart" },
          { "label": "Changelog", "href": "/changelog" }
        ]
      },
      {
        "heading": "Developers",
        "items": [
          { "label": "API Reference", "href": "/api" },
          { "label": "CLI", "href": "/guides/cli-reference" }
        ]
      }
    ]
  }
}
```