FREE Virtual Training Event | April 22, 2021
Register Now >


You are reading an unstable version of this documentation. If you want up-to-date information, please have a look at 0.1.21 .


Configuration options for this theme.

Template Options

Template-level settings can be configured via your in html_theme_options. For example:

html_theme_options = {
    'header_links': [
    ('Scylla Theme', ''),
    ('Scylla University', ''),
    ('ScyllaDB Home', '')],
    'site_description': 'Sphinx Theme for ScyllaDB projects.',
    'github_issues_repository': 'scylladb/sphinx-scylladb-theme',
    'show_sidebar_index': 'false',
    'hide_banner': 'true',
    'default_branch': 'master',
    'branch_substring_removed': 'branch-',
    'tag_substring_removed': '-scylla'
  • header_links: Links displayed in the top navbar.

  • site_description: Short summary describing the site. Metadescriptions are mainly used by search engines.

  • github_issues_repository: Repository organization name and project slug, separated by a slash (/). Used by the “Report an Issue on this Page” button.

  • show_sidebar_index: Set to true to display the left sidebar in the index page.

  • hide_banner: Set to true to show the ScyllaDB Summit registration banner at the top of the page.

  • default_branch: Name of the default branch where changes are integrated. Defaults to master.

  • branch_substring_removed: Part of the branch name to skip. When the project does not set this option, the theme removes the prefix branch- for all releases listed in the multiversion dropdown.

  • tag_substring_removed: Part of the tag name to skip. When the project does not set this option, the theme removes the suffix -scylla for all releases listed in the multiversion dropdown.

Multiversion Options

The theme supports the extension sphinx-multiversion for building self-hosted versioned documentation.


Maintaining multiple versions is expensive. Consider building docs for a version only if this introduces relevant breaking changes reflected in the documentation.

Defining supported versions

The properties smv_tag_whitelist and smv_branch_whitelist in docs/source/ defines regular expressions with the pattern for tags/branches supported. If you only want to support a subset of versions, modify the regular expression to accept a list of tags. For example, smv_tag_whitelist = r'\b(3.22.0-scylla|3.21.0-scylla)\b' would only build the documentation for the tags 3.22.0-scylla and 3.21.0-scylla.

The variable smv_latest_version in defines which branch or tag is considered the latest. This is used to redirect users to the latest version of the docs automatically once they open the main project URL.

The extension allows configuring extra parameters. To know more about them, refer to sphinx-multiversion documentation.

Disabling multiversion support

  1. Set the properties smv_tag_whitelist and smv_branch_whitelist in to None.

smv_tag_whitelist = None
smv_branch_whitelist = None


TAGS = []
smv_tag_whitelist = multiversion_regex_builder(TAGS)
smv_branch_whitelist = multiversion_regex_builder(BRANCHES)
  1. On .github/workflows/pages.yml, change the command make multiversion for make dirhtml.

Defining a stable URL

We encourage every project to rename the latest version output directory to stable. The purpose is to have default documentation links that do not change, which is beneficial for SEO purposes and referencing docs on other websites.

You can override the latest version output directory via your with the setting smv_rename_latest_version.

Here’s an example:

smv_latest_version = 'x.y.z'        # Use the branch/tag name
smv_rename_latest_version = 'latest' # Use the commit hash


Other projects have decided to build docs for the master branch. Since this branch is used normally to integrate changes, it might be possible that the docs are not aligned with the latest stable version.