Designing your archives

Buttondown is fairly opinionated about the best reading experience being friendly and minimal.

You can customize the design and functionality of your newsletter archives in Buttondown's archive settings.

Display a customizable message at the top of your archive pages. You can configure:

• Visibility: Choose who sees the announcement (everyone, free subscribers only, logged out visitors only, or paid subscribers only)
• Message: The text to display, with support for Markdown links
• Background color: Customize the bar's background color, or leave empty to use your newsletter's tint color

Enable dark mode support so your archives automatically match your reader's system preference for light or dark mode.

Customize the header and footer sections of your archive pages using Buttondown's rich text editor. You can add text, links, subscribe buttons, subscribe forms, and other elements.

Add custom links to your archive's navigation bar. This is useful for linking to external pages like your main website, social media profiles, or other resources.

Allow subscribers to search through your archive to find specific content.

Track page views on your archive to understand how readers engage with your content.

Buttondown comes with several built-in themes you can choose from. Each has its own dedicated page with a live preview, its configurable settings, and a changelog:

• Arbus — an Instagram-inspired grid theme for image-heavy newsletters.
• Classic — a traditional, clean list layout for text-focused newsletters.
• Lovelace — a brutalist, nearly no-CSS theme that embraces browser defaults.
• Modern — a contemporary, card-based layout for visual newsletters.

You can view all available themes and their source code in the buttondown/themes repository.

You can use custom CSS to fully customize the styling of your newsletter archives.

Unlike email CSS, archive CSS runs in a normal modern browser, so you can use the full modern feature set — CSS grid, custom properties, :has(), color-mix(), and so on. (The "write CSS like it's 2005" caveat on the email design page applies to emails only.)

The Modern theme is built almost entirely on CSS custom properties (design tokens). Overriding a token is the cleanest, most upgrade-safe way to restyle your archive: change it once on :root and it cascades everywhere the theme uses it. Reach for these before overriding individual classes.

For example, to brand your entire archive with a single color:

:root {
  --color-action: #5b3df5;
}

If you've enabled dark mode, Buttondown overrides the color tokens under a :root.supports-dark-mode selector when the reader prefers a dark theme. A hard-coded hex value (e.g. background: #fff) won't adapt, but a token override on plain :root applies to both modes. To set a different value per mode:

:root {
  --color-action: #5b3df5; /* light mode */
}

@media (prefers-color-scheme: dark) {
  :root.supports-dark-mode {
    --color-action: #8b7cff; /* dark mode */
  }
}

These style the list of posts on your archive's home page (the landing page at your archive's root URL).

There are two families of buttons, and it's a common mistake to target the wrong one. The call-to-action buttons that appear inside your posts and pages use the buttondown-button family. The buttons inside the subscribe and payment forms use the archive__button family.

Some of the theme's most useful styling is already built in and toggled by data attributes rather than classes. Rather than reinventing these, you can switch them on (or restyle them) directly.