---
title: Navbar and footer
description: Configure top navigation links, calls to action, and footer content.
---

Navbar and footer settings control global links that appear across your docs
site. Use them for high-value actions, product links, support links, social
profiles, and legal pages.

Internal navbar and footer links can also make pages routable even when those
pages are not listed in the main navigation.

## Navbar structure

The navbar supports:

| Key | Purpose |
| --- | --- |
| `blur` | Enables or disables navbar background blur |
| `primary` | Main call to action |
| `secondary` | Secondary call to action |
| `links` | Up to three standard links |

```json
{
  "navbar": {
    "blur": true,
    "primary": {
      "text": "Get started",
      "href": "https://app.example.com/sign-up"
    },
    "secondary": {
      "text": "Contact sales",
      "href": "https://example.com/contact"
    },
    "links": [
      {
        "text": "Home",
        "href": "https://example.com",
        "icon": "lucide:house"
      }
    ]
  }
}
```

## Navbar items

Navbar items need `text` and `href`. They can also include an `icon`.

```json
{
  "text": "Dashboard",
  "href": "https://app.example.com/dashboard",
  "icon": "lucide:layout-dashboard"
}
```

`href` can be:

- An external URL starting with `http://` or `https://`.
- An internal docs path starting with `/`.

Internal docs paths must point to an existing MDX page in the docs root.

## Primary button color

Only `navbar.primary` supports `color`.

```json
{
  "navbar": {
    "primary": {
      "text": "Start building",
      "href": "https://app.example.com/sign-up",
      "color": {
        "light": "#171717",
        "dark": "#f5f5f5"
      }
    }
  }
}
```

Use this when the main call to action needs a brand color. Secondary items and
standard links do not support `color`.

## Navbar links

`navbar.links` can include up to three items.

Use these for links readers may need from anywhere in the docs, such as:

- Product home.
- Dashboard or app.
- API status.
- Support.
- Changelog.

Keep labels short. Long navbar labels can crowd the top navigation.

## Assistant navbar button

The assistant navbar button is configured in `assistant.navbarButton`, not
`navbar.links`.

```json
{
  "assistant": {
    "navbarButton": {
      "enabled": true,
      "text": "Ask"
    }
  }
}
```

Use this when the assistant should appear as a dedicated top-nav action instead of a
normal link.

## Footer socials

Use `footer.socials` for social or community links.

```json
{
  "footer": {
    "socials": {
      "github": "https://github.com/acme",
      "x": "https://x.com/acme",
      "linkedin": "https://linkedin.com/company/acme"
    }
  }
}
```

Supported social keys:

```txt
x, website, facebook, youtube, discord, slack, github, linkedin, instagram,
hacker-news, medium, telegram, bluesky, threads, reddit, podcast
```

Social values must be valid URLs.

## Footer links

Use `footer.links` for legal pages, support pages, status pages, and other
global references.

```json
{
  "footer": {
    "links": [
      {
        "text": "Privacy",
        "href": "https://example.com/privacy"
      },
      {
        "text": "Support",
        "href": "https://example.com/support"
      }
    ]
  }
}
```

Footer link objects support only `text` and `href`.

## Internal links and routable pages

When a navbar or footer link points to an internal docs page, that page is
included in the built site even if it is not listed in the main navigation.

```json
{
  "footer": {
    "links": [
      {
        "text": "Security",
        "href": "/legal/security"
      }
    ]
  }
}
```

The target file must exist at `legal/security.mdx` under the docs root.

Use this for pages readers should be able to access globally, but that do not
belong in the main sidebar.

## Common questions

<AccordionGroup>
  <Accordion title="Can navbar links point to docs pages?">
    Yes. Use an internal path that starts with `/`, such as
    `/getting-started/quickstart`. The target MDX file must exist in the docs
    root.
  </Accordion>

  <Accordion title="How many navbar links can I add?">
    `navbar.links` supports up to three items. Use the primary and secondary
    actions for the most important calls to action.
  </Accordion>

  <Accordion title="Can footer links have icons?">
    No. Footer link objects support only `text` and `href`. Use
    `footer.socials` for social icons.
  </Accordion>

  <Accordion title="Why is my internal footer page available even though it is not in navigation?">
    Internal navbar and footer links make target pages routable. This lets you
    publish global pages, such as legal or support pages, without adding them to
    the main sidebar.
  </Accordion>
</AccordionGroup>

## Next pages

<Columns columns={3}>
  <Column>

  <Card title="Navigation" href="/configure-with-docs-json/navigation" icon="lucide:list-tree">
    Shape the sidebar.
  </Card>

  </Column>
  <Column>

  <Card title="Branding" href="/configure-with-docs-json/branding" icon="lucide:palette">
    Configure identity.
  </Card>

  </Column>
  <Column>

  <Card title="Customize Knowledge Assistant" href="/knowledge-assistant/customize-assistant" icon="lucide:sliders-horizontal">
    Add the AI action.
  </Card>

  </Column>
</Columns>