Sphinx Bootstrap Theme

Common errors

• Bootstrap theme isn't loading javascript parts / Navbar isn't working correctly

  cause Often due to conflicts with existing jQuery or other JavaScript, or incorrect loading of theme's JS/CSS assets.
  fix Ensure `html_theme_path` and `html_theme = 'bootstrap'` are correctly set in `conf.py`. Check browser console for JavaScript errors. Ensure no conflicting jQuery versions are loaded or that your custom JS uses `$jqTheme` for theme-related interactions.

• Sidebar T.O.C isn't working / Table of contents not showing

  cause Incorrect configuration of `html_sidebars` or issues with the theme's JavaScript responsible for rendering the table of contents.
  fix Verify that `html_sidebars` is configured to include the global or local table of contents (e.g., `['localtoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html']`). Check theme options related to TOC depth. If using a custom `globaltoc.html`, ensure it's correct.

• Theme not applying / Build errors after changing theme

  cause New themes can sometimes conflict with existing Sphinx configuration options, particularly `html_sidebars`, `html_theme_path`, or `html_theme_config`.
  fix Temporarily comment out or unset `html_sidebars`, `html_theme_path`, or `html_theme_config` in your `conf.py` and rebuild. If the build succeeds, reintroduce options one by one to identify the conflict.

Warnings

• gotcha The theme supports Bootstrap v2.3.2 and v3.3.7. Bootstrap 3 has known limitations such as dropped support for sub-menus in the navigation. Ensure you set `bootstrap_version` in `html_theme_options` to your desired version (default is '3').
  Fix: Explicitly set `html_theme_options = {'bootstrap_version': '3'}` or `'2'` in your `conf.py` based on your needs. If compatibility issues arise, try '2'.
• gotcha The theme integrates its own jQuery (as `$jqTheme`) using `noConflict()` to avoid clashes with Sphinx's internal jQuery. Custom JavaScript that directly relies on `$` for jQuery might encounter conflicts or unexpected behavior.
  Fix: When writing custom JavaScript, use `$jqTheme` instead of `$` for jQuery operations if you need to interact with the theme's Bootstrap components, or ensure your custom JS is carefully isolated.
• breaking Upgrading Bootstrap versions (even within the theme) can break custom CSS or JavaScript that relies on specific Bootstrap class names or HTML structures, as these frequently change between major Bootstrap versions.
  Fix: Review the Bootstrap migration guides (e.g., Bootstrap 2 to 3, or 3 to 4/5 if using a different theme) and update your custom CSS/JS to match the new class names. For `v0.5.0`, `bootswatch_css_custom` override was removed in favor of idiomatic Sphinx CSS overrides.
• gotcha If `navbar_title` is not explicitly set in `html_theme_options`, the theme defaults to using the `project` variable from `conf.py`. This often includes version numbers which might not be desirable for a clean navigation bar title.
  Fix: Set `html_theme_options = {'navbar_title': 'Your Project Name'}` to control the exact title displayed in the navigation bar.

Install

• pip install sphinx-bootstrap-theme Install with pip

Imports

• sphinx_bootstrap_theme

  import sphinx_bootstrap_theme

  Imported to get the theme's path dynamically.
• html_theme

  html_theme = 'bootstrap'

  Sets the active HTML theme for Sphinx.
• html_theme_path

  html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()

  Directs Sphinx to where the 'bootstrap' theme is located after installation.

Quickstart

To quickly use the theme, install it via pip, then update your Sphinx project's `conf.py` file with the specified imports and theme configuration. This snippet also shows common `html_theme_options`.

# conf.py
import os
import sys
import sphinx_bootstrap_theme

project = 'My Project'
copyright = '2026, My Team'
author = 'My Team'

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon'
]

html_theme = 'bootstrap'
html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()

html_theme_options = {
    'bootstrap_version': '3', # Can be '2' or '3'
    'navbar_sidebarrel': False, # Remove 'prev' and 'next' links from navbar
    'navbar_links': [
        ("Home", "index"),
        ("About", "about"),
        ("GitHub", "https://github.com/your-org/your-project", True)
    ],
    'bootswatch_theme': "flatly", # Example: "flatly", "journal", etc.
    'navbar_title': "My Project Docs"
}