📱 Theme layout#

Breeze provides a flexible layout system with configurable component slots.

Layout structure#

The page layout consists of these main regions:

header_start

header_end

header_tabs

sidebar_primary

article_header

content

article_footer

sidebar_secondary

footer

Component slots#

Configure which components appear in each slot via html_theme_options:

html_theme_options = {
    "header_start": ["header-brand.html", "version-switcher.html"],
    "header_end": ["search-button.html", "lang-switcher.html", "theme-switcher.html", "external-links.html"],
    "sidebar_primary": ["sidebar-nav.html"],
    "sidebar_secondary": ["sidebar-toc.html", "repo-stats.html", "edit-this-page.html", "sidebar-ethical-ads.html"],
    "article_header": ["breadcrumbs.html"],
    "article_footer": ["related-pages.html"],
    "footer": ["footer-copyright.html", "external-links.html"],
}

Note

Components are often designed for a specific layout slot and may rely on the surrounding structure, spacing, or behavior of that slot.

If a component does not work as expected when placed in a different slot, this does not necessarily indicate a bug. If you believe it should be usable in another slot, please open an issue to discuss the intended usage.

Available components#

Component	Description
`breadcrumbs.html`	Breadcrumb navigation
`edit-this-page.html`	Edit on GitHub/GitLab link
`external-links.html`	External link buttons
`footer-copyright.html`	Copyright notice
`header-brand.html`	Logo and site title
`lang-switcher.html`	Language selector dropdown
`page-actions.html`	Copy page, view source, AI integration
`related-pages.html`	Previous/next page links
`repo-stats.html`	Repository stars and forks
`search-button.html`	Search trigger button
`sidebar-ethical-ads.html`	Read the Docs ads placeholder
`sidebar-nav.html`	Main navigation tree
`sidebar-toc.html`	Page table of contents
`theme-switcher.html`	Light/dark mode toggle
`version-switcher.html`	Documentation version dropdown

Page-level options#

Control layout per-page using file frontmatter (MyST) or meta directive (RST).

Hide sections#

MyST

---
hide-sidebar-primary: true
hide-sidebar-secondary: true
hide-header-tabs: true
---

RST

:hide-sidebar-primary: true
:hide-sidebar-secondary: true
:hide-header-tabs: true

Hide components#

Hide specific components on individual pages:

MyST

---
hide-breadcrumbs: true
hide-related-pages: true
hide-page-actions: true
---

RST

:hide-breadcrumbs: true
:hide-related-pages: true
:hide-page-actions: true

Custom content width#

Set a custom maximum width for page content:

MyST

---
content-width: 50rem
---

RST

:content-width: 50rem

Header tabs#

Enable or disable header navigation tabs:

html_theme_options = {
    "header_tabs": True,  # default
}

When enabled, top-level toctree entries appear as tabs in the header.

Emoji handling#

Control emoji display in different areas:

html_theme_options = {
    "emojis_title": False,        # Page titles (navigator tab)
    "emojis_header_nav": False,   # Header navigation
    "emojis_sidebar_nav": False,  # Sidebar navigation
    "emojis_sidebar_toc": False,  # Table of contents
}