{"id":8667,"library":"sphinx-bootstrap-theme","title":"Sphinx Bootstrap Theme","description":"Sphinx Bootstrap Theme integrates the Bootstrap CSS/JavaScript framework with Sphinx documentation, offering various layout options, hierarchical menu navigation, and mobile-friendly responsive design. It is configurable, extensible, and supports different Bootswatch CSS themes. The current version is 0.8.1. Releases occur irregularly, indicating active but not rapid development.","status":"active","version":"0.8.1","language":"en","source_language":"en","source_url":"https://github.com/ryan-roemer/sphinx-bootstrap-theme","tags":["Sphinx","theme","Bootstrap","documentation","frontend","responsive"],"install":[{"cmd":"pip install sphinx-bootstrap-theme","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Core documentation generator that this theme extends.","package":"Sphinx"}],"imports":[{"note":"Imported to get the theme's path dynamically.","symbol":"sphinx_bootstrap_theme","correct":"import sphinx_bootstrap_theme"},{"note":"Sets the active HTML theme for Sphinx.","symbol":"html_theme","correct":"html_theme = 'bootstrap'"},{"note":"Directs Sphinx to where the 'bootstrap' theme is located after installation.","symbol":"html_theme_path","correct":"html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()"}],"quickstart":{"code":"# conf.py\nimport os\nimport sys\nimport sphinx_bootstrap_theme\n\nproject = 'My Project'\ncopyright = '2026, My Team'\nauthor = 'My Team'\n\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx.ext.napoleon'\n]\n\nhtml_theme = 'bootstrap'\nhtml_theme_path = sphinx_bootstrap_theme.get_html_theme_path()\n\nhtml_theme_options = {\n    'bootstrap_version': '3', # Can be '2' or '3'\n    'navbar_sidebarrel': False, # Remove 'prev' and 'next' links from navbar\n    'navbar_links': [\n        (\"Home\", \"index\"),\n        (\"About\", \"about\"),\n        (\"GitHub\", \"https://github.com/your-org/your-project\", True)\n    ],\n    'bootswatch_theme': \"flatly\", # Example: \"flatly\", \"journal\", etc.\n    'navbar_title': \"My Project Docs\"\n}","lang":"python","description":"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`."},"warnings":[{"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'.","message":"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').","severity":"gotcha","affected_versions":"<=0.8.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<=0.8.1"},{"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.","message":"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.","severity":"breaking","affected_versions":"0.5.0 and later (especially if upgrading from older versions)"},{"fix":"Set `html_theme_options = {'navbar_title': 'Your Project Name'}` to control the exact title displayed in the navigation bar.","message":"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.","severity":"gotcha","affected_versions":"<=0.8.1"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"Often due to conflicts with existing jQuery or other JavaScript, or incorrect loading of theme's JS/CSS assets.","error":"Bootstrap theme isn't loading javascript parts / Navbar isn't working correctly"},{"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.","cause":"Incorrect configuration of `html_sidebars` or issues with the theme's JavaScript responsible for rendering the table of contents.","error":"Sidebar T.O.C isn't working / Table of contents not showing"},{"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.","cause":"New themes can sometimes conflict with existing Sphinx configuration options, particularly `html_sidebars`, `html_theme_path`, or `html_theme_config`.","error":"Theme not applying / Build errors after changing theme"}]}