{"id":4265,"library":"sphinx-book-theme","title":"Sphinx Book Theme","description":"Sphinx Book Theme is a lightweight Sphinx theme designed to mimic the look-and-feel of an interactive book, utilizing Bootstrap 5 for visual elements and functionality. It provides visual classes tailored for Jupyter Notebooks, supporting cell inputs, outputs, and interactive features. The current version is 1.2.0, released in March 2026. However, the project is officially in maintenance mode, accepting bug fixes but with limited new feature development due to a lack of dedicated resources.","status":"maintenance","version":"1.2.0","language":"en","source_language":"en","source_url":"https://github.com/executablebooks/sphinx-book-theme","tags":["sphinx","theme","documentation","books","scientific","jupyter","bootstrap"],"install":[{"cmd":"pip install sphinx-book-theme","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Required for generating documentation; theme builds on Sphinx's core functionality. Minimum version 7.0 for v1.2.0.","package":"sphinx"},{"reason":"Sphinx Book Theme inherits a lot of functionality and design rules from PyData Sphinx Theme. Minimum version 0.15.4 for v1.2.0.","package":"pydata-sphinx-theme"},{"reason":"Requires Python 3.11 or newer.","package":"python"}],"imports":[{"note":"To activate the theme, set 'html_theme' in your project's conf.py file. This is not a Python import in the traditional sense, but a configuration setting.","symbol":"html_theme","correct":"html_theme = \"sphinx_book_theme\""}],"quickstart":{"code":"# 1. Create a new Sphinx project (if you don't have one)\nsphinx-quickstart\n\n# 2. Install the theme\npip install sphinx-book-theme\n\n# 3. Edit conf.py in your Sphinx project's source directory\n#    Add 'sphinx_book_theme' to the html_theme variable:\n#    html_theme = \"sphinx_book_theme\"\n#    Optionally, add theme options, e.g., for a GitHub button:\n#    html_theme_options = {\n#        \"repository_url\": \"https://github.com/executablebooks/sphinx-book-theme\",\n#        \"use_repository_button\": True,\n#        \"path_to_docs\": \"docs\", # relative path to docs root from repo root\n#        \"home_page_in_toc\": True,\n#    }\n\n# 4. Create an index.rst (or .md if using MyST-parser) and other content files\n#    Example index.rst:\n#    ====================\n#    Welcome to My Book!\n#    ====================\n#\n#    .. toctree::\n#       :hidden:\n#       :maxdepth: 2\n#       :caption: Contents\n#\n#       page1\n#       page2\n\n# 5. Build your documentation\nmake html # or sphinx-build -M html . _build","lang":"bash","description":"To quickly set up documentation with Sphinx Book Theme, first initialize a Sphinx project using `sphinx-quickstart`. Then, install the theme via pip. The core step involves modifying your `conf.py` file to set `html_theme = \"sphinx_book_theme\"` and optionally configure `html_theme_options` for features like a repository link. Finally, build your documentation using `make html` or `sphinx-build`."},"warnings":[{"fix":"Be aware of the project's status and consider contributing if urgent fixes or features are needed.","message":"The Sphinx Book Theme project is currently in 'maintenance mode'. This means new feature development is unlikely, and bug fixes may be slower or depend on community contributions. Users should manage expectations for active development.","severity":"gotcha","affected_versions":"All current and future versions under maintenance mode"},{"fix":"Thoroughly review your custom CSS and HTML templates against the new theme structure. Consult the official changelog and migration guides if available.","message":"The v1.0.0 release introduced a 'major refactor' of the theme's HTML structure and updated its base, PyData Sphinx Theme. Projects with existing custom CSS or HTML templates from pre-1.0 versions may require significant re-configuration and adjustments to maintain their appearance and functionality.","severity":"breaking","affected_versions":"1.0.0 and later"},{"fix":"After upgrading, always rebuild and review your documentation for any visual regressions. Be prepared to update `html_theme_options` or custom CSS.","message":"As 'sphinx-book-theme' heavily depends on 'pydata-sphinx-theme', updates to the parent theme can introduce unexpected style changes or require adjustments to `html_theme_options`. Specifically, versions 1.1.3 and 1.1.4 noted 'breaking style changes in pydata-sphinx-theme'.","severity":"gotcha","affected_versions":"1.1.3, 1.1.4, and potentially others inheriting from updated PyData Sphinx Theme versions"},{"fix":"If experiencing issues with CSS overrides, check the generated HTML for duplicate CSS imports. Consider using more specific selectors or `!important` as a last resort, or investigate the theme's CSS build process.","message":"A historical issue (Issue #496) reported that `sphinx-book-theme.css` was sometimes imported twice, which could prevent user-defined custom CSS from correctly overriding theme styles due to load order problems. While potentially fixed, users attempting deep CSS customization should be vigilant.","severity":"gotcha","affected_versions":"Older versions (pre-1.1.0); inspect rendered HTML for current status"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}