2 Apr 2026

Top navigation¶

You can edit the default contents of the top navigation by customizing source view button behaviour, adding custom tabs and hiding the dark mode switch.

Customizing source view buttons¶

The View source button is displayed if the page has been generated from source (not autogenerated) and source display is allowed.

You can hide the button by using built-in Sphinx config variable html_show_sourcelink:

conf.py¶

html_show_sourcelink = True

Custom URLs¶

By default, the button will link to the source file produced by Sphinx. To override this behaviour and instead make the buttons point somewhere else, you can set the source_view_link theme option:

conf.py¶

html_theme_options = {
    ...
    "source_view_link": f"https://codeberg.org/{REPO}/src/branch/HEAD/docs/$truncated?display=source"
}

You can use the following variables in the link:

Variable	Description
`$source`	Same as `sourcename` variable in template.
`$truncated`	`$source`, but without `_sources/` and `.txt`.

Edit source button¶

The Edit source button will appear if the View source button is displayed and if the source_edit_link is set:

conf.py¶

html_theme_options = {
    ...
    "source_edit_link": f"https://codeberg.org/{REPO}/_edit/HEAD/docs/$truncated"
}

You can use the same variables as in source_view_link.

Adding custom tabs¶

If you have set up template overrides like so:

conf.py¶

templates_path = ['_templates']

You can override the page.html template to add your custom tab. To do so, override the topnav block and put your tabs before or after the super call, depending on where you’d like them placed:

page.html¶

{% extends "!page.html" %}

{% block topnav %}
    {{ super() }}
    
    <a class="mcl-nav-button" href="/characters/privaty.html" target="_blank">
        Sample Text
    </a>
{% endblock %}

Refer to Templating section of Sphinx’s own documentation to see what’s available in the templates.

Right-hand navigation¶

Same approach can be used to add buttons to the right-hand side of the top navigation, however the block is different:

layout.html¶

{% extends "!layout.html" %}

{% block topnav_alt %}
    <a class="mcl-nav-button" href="/characters/privaty.html" target="_blank">
        Sample Text
    </a>
    
    {{ super() }}
{% endblock %}

Contents of topnav_alt is hidden in the mobile layout by default together with the search bar. If you want your content to remain visible on mobile, add the mcl-topnav-important class to it.

Disabling dark mode switch¶

Note

Disabling dark mode switch will prevent users from enabling and disabling dark mode manually, but it will still be used if the user agent is configured to load websites with dark theme by default.

You can disable the dark mode switchby setting the nightshift_switch option:

conf.py¶

html_theme_options = {
    ...
    "nightshift_switch": False
}

CSS Variables¶

The following CSS variables influence the look and feel of Top Navigation:

Top navigation
Variable	Default value		Description
Variable	Light mode	Dark mode	Description
`--mcl-top-nav-bg`	`var(--mcl-document-top-bg)`		Color of the top of the document on which the top navigation “sits”.
`--mcl-top-nav-trispective-right`	`var(--mcl-header-trispective-bottom)`		Color of the triangle layered over the top of the document on which the top navigation “sits”. Match it with the background of your page to give the document a nice isometric look. Tip You can use your browser’s color picker for this, acutally!
Buttons/Tabs
Variable	Default value		Description
Variable	Light mode	Dark mode	Description
`--mcl-top-nav-btn-bg`	`var(--mcl-document-top-bg)`		Background of top navigation button/tab.
`--mcl-top-nav-btn-active-bg`	`var(--mcl-document-bg)`		Background of top navigation button/tab, that is currently active.
`--mcl-top-nav-btn-bg-sprite`	`imagery/bg-tab.png`	`imagery/bg-tab-dark.png`	Sprite overlayed on top of top navigation buttons/tabs.
`--mcl-top-nav-btn-trispective-right`	`var(--mcl-header-trispective-top)`		Color of the triangle layered over the top navigation button/tab (top right corner). Match it with the background of your page to give the element a nice isometric look.
`--mcl-top-nav-btn-trispective-left`	`var(--mcl-document-top-bg)`		Color of the triangle layered over the top navigation button/tab (bottom left corner).
`--mcl-top-nav-btn-trispective-left-alt`	`#432611`	`#281D16`	Color of the triangle layered over the first top navigation button/tab (bottom left corner).
`--mcl-mobile-top-nav-btn-filter`	`none`	`invert()`	Filter applied to buttons on mobile header menu.
Search bar and Dark Mode Switch
Variable	Default value		Description
Variable	Light mode	Dark mode	Description
`--mcl-search-bar-color`	`hwb(0 0% 100%)`	`var(--mcl-text-color)`	Color of text in the search bar.
`--mcl-search-bar-placeholder-color`	`var(--mcl-text-color-alt)`	`#AAA`	Color of the placeholder text in the search bar.
`--mcl-search-bar-top-bg`	`hwb(0 100% 0%)`	`hwb(0 0% 100%)`	Color of the top side of the search bar.
`--mcl-search-bar-side-bg`	`hwb(0 53% 47%)`	`hwb(0 7% 93%)`	Color of the left side of the search bar.
`--mcl-search-bar-bg-gradient`	`linear-gradient(hwb(0 76% 24%), hwb(0 86% 14%))`	`linear-gradient(hwb(0 24% 76%), hwb(0 14% 86%))`	Background gradient of the search bar. Set to `none` if you want to only use the fallback color.
`--mcl-search-bar-bg-fallback`	`hwb(0 81% 18%)`	`hwb(0 18% 81%)`	Fallback color of the search bar if the gradient rule fails to be parsed by user agent.
`--mcl-search-bar-bg-bleacher`	`hwb(0 100% 0% / 0.5)`	`hwb(0 0% 100% / 0.5)`	Background color of input, button or icons in the search bar.
`--mcl-search-bar-trispective-left`	`var(--mcl-document-top-bg)`		Color of the triangle layered over the search var (bottom left corner).
`--mcl-search-bar-trispective-right`	`var(--mcl-header-trispective-top)`		Color of the triangle layered over the search var (top right corner).