Release announcements

Point readers to a release, let them dismiss the notice and publish the next announcement.

An announcement gives readers a short message above the site header, with an optional link to the full story. Use it for a new release, a migration guide or a community event. Readers can close the notice and continue through the site without seeing it on every page.

Development preview

The announcement banner is available since v0.8.0.

Publish your first announcement

  1. Publish the destination first.

    Create the release post using the Blog recipe and confirm its public address. The example below assumes your site already has a post at /blog/acme-1-0/.

  2. Add the announcement to zola.toml.

    [extra.devlab.announcement]
show = true
key = "acme-release-1.0"
label = "Release"
message = "Acme 1.0 is available"
path = "/blog/acme-1-0/"
dismissible = true

    Replace the project name, key and path with your own values. If the table already exists, edit its fields; TOML does not allow declaring the same table twice.

  3. Preview the result.

    zola check
zola serve

    Open Home and a Docs page. Follow the announcement link, close the notice and reload the page. It should remain hidden in that browser when storage is available. Open the destination manually too: a public path in configuration does not create a page or prove that it exists.

The banner is disabled by default. It appears across layouts that use DevLab's base template when show = true and message is non-empty. Keep these settings in the site configuration; there is no per-page announcement override.

Write a message that fits

message and label are plain text. Put the destination in path; Markdown links and HTML in the message are displayed as text.

Keep the important information in message, such as the project name and release number. The optional label is a small prefix that disappears at widths of 420px or less. Long messages are shortened on desktop and limited to two lines on mobile, so put release details in the linked article.

The banner stays above the header while scrolling. DevLab adjusts the header, Docs sidebar, table of contents and heading offsets when it appears or closes. Its colors follow the theme's accent palette; Brand and colors explains how to change that palette.

Choose where the message leads

Use a local route such as /blog/acme-1-0/ or an absolute HTTPS URL to an external release page. Local routes include the site's deployment prefix and active content language. Use the site's route without manually adding that prefix or language code.

On a multilingual site, make sure the destination exists in each language that displays the announcement. The banner does not check for missing translations or choose a fallback destination.

For a notice without a destination, set path = "". The message remains visible as text, with no link or arrow. A Blog section is only needed when the chosen destination belongs to your Blog.

Publish the next announcement

Keep key unchanged when correcting a typo or adjusting the link. Readers who already dismissed that announcement will continue to have it hidden.

When there is something new to announce, update the key, message and destination together:

[extra.devlab.announcement]
show = true
key = "acme-release-1.1"
label = "Release"
message = "Acme 1.1 is available"
path = "/blog/acme-1-1/"
dismissible = true

Use a fresh key for each announcement. DevLab remembers the most recently dismissed key, not a history of every notice the reader has closed.

Control visibility and closing

Change these fields inside the existing announcement table:

What you wantWhat to change
Remove the announcement for everyoneSet show = false
Keep the notice visible without a close buttonSet dismissible = false
Let readers close the noticeSet dismissible = true and provide a non-empty key
Remove the small prefixSet label = ""

Turning show off does not clear saved dismissals. If you turn it back on with the same key, readers who closed it still have it hidden. An empty message also removes the banner.

Closing requires JavaScript. With JavaScript disabled, the announcement and its link remain usable, but the close button cannot dismiss it. If JavaScript works and storage is blocked, closing still hides the notice on the current page; it can return after navigation or a reload.

The preference belongs to the current browser profile and site origin. It is not shared with another device, and clearing site data can make the notice reappear. Language routes and projects hosted under different subpaths of the same origin share that storage. Use project-specific keys such as acme-release-1.1 to avoid matching another project's announcement by accident.

Change the accessible labels

Set the visible copy through label and message. The banner's accessible name and the close button's label are separate:

[extra.labels]
announcement = "Объявление"
announcement_dismiss = "Закрыть объявление"

The defaults are Announcement and Dismiss announcement. Merge these fields into an existing [extra.labels] table when necessary. They change the interface labels; they do not translate the message or set up a language switcher.

If the banner does not behave as expected

  • It never appears: confirm that your installed theme includes the feature, show = true and message is non-empty. If you already closed it, preview with a temporary key, then restore the publication key before committing.
  • The close button is missing: check both dismissible and key. A blank key removes the close button.
  • It returns after closing: check that the key stays the same between pages and builds and that the browser allows persistent storage. Reload an already open tab to apply a dismissal made in another tab.
  • The link opens a missing page: check the published route and, for a translated site, the destination in the active language.

For exact field types and defaults, see Announcements in the configuration reference.