Announcements

Clarity Theme for Sphinx makes it easy to display an announcement banner at the top of the pages.

You can add an announcement banner to draw extra attention from your reader like a new major release, or a summer sale.

Setting announcement

To show the announcement bar, in conf.py:

1. Set html_theme_options’s announcement option to arbitrary content.

   html_theme_options = {
       "announcement": "New version 2.0 is out!"
   }
   

2. Rebuild the docs.

HTML content

The announcement option value may be arbitrary HTML that is rendered as-is, only with basic styling to underline links, etc.

html_theme_options = {
    "announcement": """<strong>New version 2.0 is out!</strong> Check out <a href="/en/stable/$PAGE$">what's new</a> in this version.""",
}

Note

If adding HTML tag attributes, wrap the string into triple quotes (""" or ''').

Conditional announcement

Since conf.py is regular Python script, you can e.g. conditionally insert announcement or modify its value. For example:

if language != "en":
    html_theme_options["announcement"] = "The non-English versions may be outdated"

The $PAGE$ placeholder

The announcement option value supports the $PAGE$ placeholder that will be replaced with the currently viewed page’s path.

For example, you want to warn that non-English translations may be outdated and provide a link to the English version of the current page.

if language != "en":
    html_theme_options["announcement"] = """See <a href="/en/$PAGE$">this page in English</a>."""

For example, if the currently viewed document is admin/install.rst, the $PAGE$ will be replaced, depending on the Sphinx builder, with admin/install/index.html for dirhtml or admin/install.html for html.