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).

{
  "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 for the full syntax): a bare name like "github" resolves to that name in the default Lucide 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.

{
  "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), 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:

{
  "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) — 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).

{
  "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 for the full syntax): a bare name like "github" resolves to that name in the default Lucide 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.