Header logo and title#

The header can show logo image, title text, or both, giving your documentation immediate branding. Swapping variants and tailoring light/dark mode versions is straightforward.

If set, by default, the both logo and title are shown. The header branding region spans roughly half the header width to fit even wide logos and titles.

Header title#

The same as page title#

By default, the header title uses Sphinx standard html_title option used for HTML page title (<title>). The default value is <project> <release> documentation. E.g., for project = "Foo" and release = "1.5", it becomes Foo 1.5 documentation.

Set page and header title

In conf.py:
```
html_title = "REST API"
```

Tip

Set the same project and HTML title:

project = html_title = "My Awesome Project"

Different than page title#

If you want header title different than html_title, use the html_theme_options’s header_title option.

Set custom header title

In conf.py:

html_title = "REST API"
html_theme_options = {
   "header_title": "Getting started with RESTful API"
}

Disable title#

To completely disable showing a header title, set the html_theme_options’s header_title option to False.

Disable header title

In conf.py:

html_theme_options = {
   "header_title": False
}

Header logo#

Same logo for light and dark mode#

Use the standard Sphinx html_logo; the file appears in both modes.

Set a header logo

In conf.py set html_logo to a path relative to conf.py or an external URL.
```
html_logo = "logo.svg"
```

Different logo for light and dark mode#

If the light logo doesn’t look good against a dark background, supply a separate dark variant.

Set a dark mode logo

Set the light variant with html_logo option.
Set the dark variant using html_theme_options’s logo_dark option.
Add the dark logo file (or its folder) to html_static_path so Sphinx copies it. (The light logo is copied automatically.)

For example:

html_static_path = ["_static"]
html_logo = "_static/logo.svg"
html_theme_options = {
      "logo_dark": "_static/logo-dark.svg"
}

Automatic dark mode logo#

Alternatively, invert the light logo automatically. This can be “good enough” if you lack a dedicated dark asset.

Turn on automatic dark logo

Set the light variant with html_logo.
Enable inversion with html_theme_options’s logo_dark_invert option.
```
html_theme_options = {
    "logo_dark_invert": True
}
```

Logo link#

The logo (or title) links to the root document by default (usually index.md / index.rst).

Change logo link

In conf.py’s html_theme_options, set logo_url option. The value might be any browser valid URL address.
```
html_theme_options = {
    "logo_url": "https://readcraft.io"
}
```

Disable logo#

To completely disable logo, just unset the html_logo option.

Unset logo, use title only

In conf.py unset the logo: html_logo = None.

Set title using html_title option.

html_logo = None
html_title = "My project"