Theme Configuration

Comprehensive configuration system with 19 options controlling navigation behavior, styling, and responsive design features.

Configuration Usage

Set options in your Sphinx conf.py:

html_theme_options = {
    'collapse_navigation': True,
    'sticky_navigation': True,
    'navigation_depth': 4,
    'includehidden': True,
    'titles_only': False,
    'logo_only': False,
    'prev_next_buttons_location': 'bottom',
    'style_external_links': False,
    'style_nav_header_background': '',
    'vcs_pageview_mode': '',
    'flyout_display': 'hidden',
    'version_selector': True,
    'language_selector': True
}

Configuration Options

Navigation Behavior

collapse_navigation

'collapse_navigation': bool  # Default: True

Controls whether navigation menu items are collapsed by default. When True, only the current page's section is expanded, keeping the sidebar compact. When False, all navigation sections remain expanded.

sticky_navigation

'sticky_navigation': bool  # Default: True

Enables sticky navigation behavior where the sidebar follows the user's scroll position. When True, the navigation stays visible as users scroll through long pages.

navigation_depth

'navigation_depth': int  # Default: 4

Sets the maximum depth of navigation tree to display in the sidebar. Deeper nested pages will not appear in the navigation menu.

includehidden

'includehidden': bool  # Default: True

Whether to include hidden toctree entries in the navigation. When True, pages marked as hidden in the toctree directive will still appear in the sidebar.

titles_only

'titles_only': bool  # Default: False

When True, displays only page titles in navigation without showing subsection headers within each page.

Visual Appearance

logo_only

'logo_only': bool  # Default: False

When True, displays only the logo in the navigation header without the project title text.

style_external_links

'style_external_links': bool  # Default: False

When True, applies special styling to external links to distinguish them from internal links.

style_nav_header_background

'style_nav_header_background': str  # Default: ''

Custom CSS styling for the navigation header background. Accepts any valid CSS background property value.

Page Navigation

prev_next_buttons_location

'prev_next_buttons_location': str  # Default: 'bottom'

Controls placement of previous/next page navigation buttons. Valid values:

• 'bottom': At the bottom of the page content
• 'top': At the top of the page content
• 'both': At both top and bottom
• 'none': Hide prev/next buttons

Version and Language Controls

version_selector

'version_selector': bool  # Default: True

Shows version selector dropdown in the navigation when multiple versions are available (typically in Read the Docs environment).

language_selector

'language_selector': bool  # Default: True

Shows language selector dropdown in the navigation when multiple languages are available (typically in Read the Docs environment).

flyout_display

'flyout_display': str  # Default: 'hidden'

Controls the display behavior of the flyout menu for versions and languages. Valid values:

• 'hidden': Hide flyout menu by default
• 'attached': Show flyout menu attached to navigation
• 'floating': Show flyout menu as floating element

Version Control Integration

vcs_pageview_mode

'vcs_pageview_mode': str  # Default: ''

Sets the version control page view mode for Read the Docs integration. This affects how edit/view source links are generated.

Deprecated Options

The following options are deprecated and will generate warnings:

canonical_url (Deprecated)

'canonical_url': str  # DEPRECATED

Replacement: Use Sphinx's built-in html_baseurl configuration option instead.

Warning: "The canonical_url option is deprecated, use the html_baseurl option from Sphinx instead."

analytics_id (Deprecated)

'analytics_id': str  # DEPRECATED

Replacement: Use the sphinxcontrib-googleanalytics extension instead.

Warning: "The analytics_id option is deprecated, use the sphinxcontrib-googleanalytics extension instead."

analytics_anonymize_ip (Deprecated)

'analytics_anonymize_ip': bool  # DEPRECATED

Replacement: Use the sphinxcontrib-googleanalytics extension instead.

Warning: "The analytics_anonymize_ip option is deprecated, use the sphinxcontrib-googleanalytics extension instead."

Theme Configuration File

The theme inherits from Sphinx's basic theme with the following configuration:

[theme]
inherit = basic
stylesheet = css/theme.css
pygments_style = default

[options]
# All 19 configuration options with their defaults
canonical_url =
analytics_id =
analytics_anonymize_ip = False
collapse_navigation = True
sticky_navigation = True
navigation_depth = 4
includehidden = True
titles_only =
logo_only =
prev_next_buttons_location = bottom
style_external_links = False
style_nav_header_background =
vcs_pageview_mode =
flyout_display = hidden
version_selector = True
language_selector = True

Usage Examples

Minimal Configuration

# Basic responsive theme with defaults
html_theme = 'sphinx_rtd_theme'

Custom Navigation

html_theme_options = {
    'collapse_navigation': False,  # Keep all sections expanded
    'navigation_depth': 2,         # Show only 2 levels deep
    'titles_only': True,           # Show only page titles
    'prev_next_buttons_location': 'both'  # Buttons top and bottom
}

Branding Customization

html_theme_options = {
    'logo_only': True,  # Show only logo, not project title
    'style_nav_header_background': '#2c3e50',  # Custom header color
    'style_external_links': True   # Highlight external links
}

Read the Docs Integration

html_theme_options = {
    'version_selector': True,      # Show version dropdown
    'language_selector': True,     # Show language dropdown
    'flyout_display': 'attached',  # Attach flyout to nav
    'vcs_pageview_mode': 'edit'    # Show edit links
}

Mobile-Optimized

html_theme_options = {
    'sticky_navigation': True,     # Keep nav visible on mobile
    'collapse_navigation': True,   # Compact navigation
    'navigation_depth': 3,         # Limit depth for mobile
    'titles_only': False          # Show subsections for context
}