Configuration¶

Every option below goes in html_theme_options. Values shown are the defaults.

Branding¶

Option	Default	Description
`logo_text`	`""`	Text next to the logo. Falls back to `html_title`.
`logo_subtitle`	`""`	Small secondary line, e.g. a version tag.
`announcement`	`""`	Gold banner pinned above the header. HTML is allowed.
`footer_note`	`""`	Small print on its own footer row.

Navigation¶

Option	Default	Description
`github_url`	`""`	Shows a GitHub icon in the header.
`discord_url`	`""`	Shows a Discord icon in the header.
`nav_links`	`[]`	List of `{"title": ..., "url": ...}` header links.
`show_breadcrumbs`	`true`	Ancestor trail above the page title.
`show_prev_next`	`true`	Previous/next panels at the end of each page.
`show_toc`	`true`	Right-hand “on this page” column.
`toc_title`	`"On this page"`	Heading for that column.
`show_source_link`	`true`	“Show source” link, when `html_show_sourcelink` is on.
`back_to_top`	`true`	Floating back-to-top button.
`globaltoc_collapse`	`false`	Start sidebar branches collapsed. Toggling is client-side, so the whole tree stays reachable either way.
`globaltoc_includehidden`	`true`	Include `:hidden:` toctree entries in the sidebar.
`globaltoc_maxdepth`	`3`	Sidebar nesting depth. `-1` for unlimited.

Edit this page¶

Set source_repository to add an “Edit this page” link. GitHub and GitLab URL shapes are both recognised.

html_theme_options = {
    "source_repository": "https://github.com/me/my-project",
    "source_branch": "main",
    "source_directory": "docs",
}

Typography¶

Option	Default	Description
`body_font`	`rs`	Body copy font. See Getting started.
`heading_font`	`rs-bold`	Heading font.
`mono_font`	system mono	Code font. Code stays in a real monospace face by default, because pixel fonts and code indentation do not mix.
`base_font_size`	`20px`	Root font size. Bare numbers are read as pixels.

Surface treatment¶

Option	Default	Description
`scanlines`	`true`	The faint stone texture on panels, cards and admonitions.
`pixelated_images`	`false`	Render every image with `image-rendering: pixelated`. Great for sprites, unkind to screenshots,hence off by default.
`css_variables`	`{}`	Override any design token. See below.

Recolouring the theme¶

Every colour, size and bevel is a CSS custom property on :root. Override them without touching the stylesheets:

html_theme_options = {
    "css_variables": {
        "rs-gold": "#7fd4ff",
        "rs-orange": "#c8e8ff",
        "rs-content-max-width": "52rem",
        "rs-sidebar-width": "300px",
    },
}

The leading -- is optional; both rs-gold and --rs-gold work.

Custom stylesheets¶

For anything the tokens do not cover, add your own stylesheet the usual way:

html_static_path = ["_static"]
html_css_files = ["custom.css"]

Sidebar contents¶

The left sidebar renders whatever is listed in html_sidebars. The default is:

html_sidebars = {
    "**": [
        "components/sidebar-brand.html",
        "components/sidebar-search.html",
        "components/sidebar-nav.html",
    ],
}

Drop templates from that list, reorder them, or add your own.

Edit this page Show source