# Topbar, footer, and socials

## `topbar.links`

An array of `{ label, icon, href }` objects, rendered top-right on every page. `href` is always required; a link needs at least one of `label` or `icon` (it can have both — the icon renders to the left of the label — or just one).

```json
{
  "topbar": {
    "links": [
      { "label": "GitHub", "icon": "github", "href": "https://github.com/your-org/your-repo" },
      { "label": "Support", "href": "mailto:support@example.com" },
      { "icon": "activity", "href": "https://status.example.com" }
    ]
  }
}
```

`icon` is resolved the same way any other `icon` string in `writedocs.json` is (see [Components](/docs/content/components/) for the full syntax): a bare name like `"github"` resolves to that name in the default [Lucide](https://lucide.dev) icon set, or use an explicit `"collection:icon-name"` key for anything else. An icon-only link (no `label`) still gets an accessible name — it falls back to the raw `icon` string as its `aria-label`.

## `footer.columns`

An array of columns rendered below the page content — each with an optional `title` and a list of links, the same `{ label, icon, href }` shape as `topbar.links` above.

```json
{
  "footer": {
    "columns": [
      {
        "title": "Resources",
        "links": [
          { "label": "Documentation", "icon": "book-open", "href": "/getting-started/" },
          { "label": "Blog", "href": "https://example.com/blog" }
        ]
      },
      {
        "title": "Community",
        "links": [
          { "label": "Discord", "href": "https://discord.gg/example" },
          { "label": "GitHub Discussions", "href": "https://github.com/example/repo/discussions" }
        ]
      }
    ]
  }
}
```

A column's `title` is optional — a column with just a bare list of links (no heading) is valid too. Columns wrap onto multiple rows on narrow screens rather than compressing.

If `styles.logo` is set (see [Styles](/docs/configuration/styles/)), it renders to the left of the columns — the same light/dark logo image(s) the topbar already shows. Set `footer.logo` (same `{ light, dark }` shape, or a single path for both) to show something different in the footer instead — a wordmark that works better small, a partner/community mark, or nothing at all if you'd rather the footer had no logo while the topbar keeps one:

```json
{
  "footer": {
    "logo": {
      "light": "/logo/footer-light.svg",
      "dark": "/logo/footer-dark.svg"
    }
  }
}
```

`footer.logo` replaces `styles.logo` entirely in the footer, rather than filling in whichever side is missing — set only `dark`, for instance, and the footer shows just that image, not `styles.logo`'s light one alongside it. Leave `footer.logo` unset (the default) and the footer keeps showing `styles.logo`, exactly as before.

The footer only renders at all once there's something to put in it — a site with no `footer.columns` and no `socials` (below) gets no `<footer>` element, not an empty bordered band. It's also hidden entirely on frontmatter `mode: blank` pages, same as the topbar (see [Page modes](/docs/content/page-modes/)) — a page that opts out of all site chrome opts out of the footer too.

## `socials`

A free-form map of platform name to profile/page URL, rendered as a row of icon links alongside the footer columns above (or on its own, if a site sets `socials` with no `footer.columns`).

```json
{
  "socials": {
    "twitter": "https://twitter.com/example",
    "github": "https://github.com/example"
  }
}
```

Each key doubles as the icon reference — it's resolved the same way any other `icon` string in `writedocs.json` is (see [Components](/docs/content/components/) for the full syntax): a bare name like `"github"` resolves to that name in the default [Lucide](https://lucide.dev) icon set, or use an explicit `"collection:icon-name"` key (e.g. `"simple-icons:x"`) when the bare Lucide name isn't right for a given platform, or doesn't exist there at all.

<Callout type="tip">
  See `docs.json-examples/00-kitchen-sink/` in the Writedocs repo for a complete, buildable example covering both footer columns and socials, including the explicit `"collection:icon-name"` form for a platform Lucide doesn't cover.
</Callout>