Reference#

Technical reference for Clarity Theme for Sphinx: theme options, template blocks, and CSS variables you can override.

HTML theme options#

Option

Default

Description

default_layout

"default"

Page layout used when no per‑page override ("default" or "compact"). Read more

header_title

""

Header title (next to the header logo). By default (blank string), it shows value of html_title. To hide header title, set to False. Read more

header_menu

[]

List of navigation items (content, url, …). Read more

logo_dark

""

Path/URL to dark mode logo variant. Read more

logo_dark_invert

false

Automatically invert light logo for dark mode when true. Read more

logo_url

""

Override default root link target for logo/text. Read more

language_select

{}

Mapping of language codes to display names for selector. Read more

language_url

""

URL pattern with placeholders like $LANGUAGE$ or $PAGE$. Read more

edit_page_label

""

The “edit page” link label. Read more

edit_page_url

""

The “edit page” link target. Read more

version_select_current

""

The current documentation version select dropdown. Read more

version_select_data

[]

List of available versions for version select dropdown. Read more

version_select_url

""

URL pattern for the version select dropdown. Read more

version_select_preferred

""

Display a warning if not viewing the preferred version. Read more

version_select_preferred_warning

""

Customized warning message if not viewing the preferred version. Read more

announcement

""

Display an announcement banner at the top of the pages. Read more

Jinja templates and blocks#

Template

Block

Description

layout.html

html_tag_attrs

Add attributes to <html> tag.

layout.html

head_tag_end

Inject code before closing </head>.

layout.html

body_tag_attrs

Add attributes to <body> tag.

layout.html

body_tag_start

Immediately after opening <body>.

layout.html

body_tag_content

Main page content (between start/end blocks).

layout.html

body_tag_end

Inject code before closing </body>.

partials/head.html

title_tag

Content of <title> tag.

partials/article_footer.html

article_footer_left

Left column of article footer.

partials/article_footer.html

article_footer_right

Right column of article footer.

CSS variables#

Many aspects of Clarity Theme for Sphinx are driven by CSS variables. Override defaults to adapt branding and visuals.

See also

Practical example: customizing theme colors.

Tip

Learn variable names via browser dev tools: How to find out variable name to override.

Colors#

The majority of CSS variables is related to colors used across the website.

/* Base background color */
--color-base-100:

/* Secondary background color, slightly darker than base-100 */
--color-base-200:

/* Tertiary background color, darker than base-200 */
--color-base-300:

/* Text color for content on base backgrounds */
--color-base-content:

/* Primary brand color for main actions and emphasis */
--color-primary:

/* Text color for content on primary background */
--color-primary-content:

/* Secondary brand color for complementary elements */
--color-secondary:

/* Text color for content on secondary background */
--color-secondary-content:

/* Accent color for highlights and special emphasis */
--color-accent:

/* Text color for content on accent background */
--color-accent-content:

/* Neutral color for borders and subtle elements */
--color-neutral:

/* Text color for content on neutral background */
--color-neutral-content:

/* Informational message color (typically blue) */
--color-info:

/* Text color for content on info background */
--color-info-content:

/* Success state color (typically green) */
--color-success:

/* Text color for content on success background */
--color-success-content:

/* Warning state color (typically yellow/orange) */
--color-warning:

/* Text color for content on warning background */
--color-warning-content:

/* Error state color (typically red) */
--color-error:

/* Text color for content on error background */
--color-error-content:

/* Heading color */
--article-heading--color: 

/* Regular text color */
--article-text--color:

/* Color of code examples */
--article-mono--color:

Fonts#

The theme uses only a few font families which you can change using the following CSS variables.

See also

Customizing theme fonts

/* Font family for general text. */
--font-sans:

/* Font family for source code examples */
--font-mono:

/* Font family for article headings */
--article-heading--font:

/* Regular text font family */
--article-text--font:

Miscellaneous#

CSS variables related to Sphinx documents generated from reStructuredText or Markdown source files.

/* Heading scale ratio */
--article-heading--scale: