UPDATE: Sphinx Book Theme 0.3 (#1679)

docs/_config.yml

@@ -17,6 +17,7 @@ execute:
   execute_notebooks: cache
 
 html:
+  announcement: "⚠️The latest release refactored our HTML, so double-check your custom CSS rules!⚠️"
   favicon: images/favicon.ico
   google_analytics_id: UA-52617120-7
   home_page_in_navbar: false

docs/_toc.yml

@@ -68,6 +68,7 @@ parts:
       sections:
       - file: interactive/comments/hypothesis
       - file: interactive/comments/utterances
+    - file: web/announcements
     - file: advanced/html
 
   - file: sphinx/index

docs/conf.py

@@ -23,7 +23,7 @@ html_logo = 'images/logo-wide.svg'
 html_sourcelink_suffix = ''
 html_static_path = ['_static']
 html_theme = 'sphinx_book_theme'
-html_theme_options = {'search_bar_text': 'Search this book...', 'launch_buttons': {'notebook_interface': 'classic', 'binderhub_url': 'https://mybinder.org', 'jupyterhub_url': '', 'thebe': True, 'colab_url': 'https://colab.research.google.com'}, 'path_to_docs': 'docs', 'repository_url': 'https://github.com/executablebooks/jupyter-book', 'repository_branch': 'master', 'google_analytics_id': 'UA-52617120-7', 'extra_navbar': 'Powered by <a href="https://jupyterbook.org">Jupyter Book</a>', 'extra_footer': '', 'home_page_in_toc': False, 'use_repository_button': True, 'use_edit_page_button': True, 'use_issues_button': True}
+html_theme_options = {'search_bar_text': 'Search this book...', 'launch_buttons': {'notebook_interface': 'classic', 'binderhub_url': 'https://mybinder.org', 'jupyterhub_url': '', 'thebe': True, 'colab_url': 'https://colab.research.google.com'}, 'path_to_docs': 'docs', 'repository_url': 'https://github.com/executablebooks/jupyter-book', 'repository_branch': 'master', 'google_analytics_id': 'UA-52617120-7', 'extra_navbar': 'Powered by <a href="https://jupyterbook.org">Jupyter Book</a>', 'extra_footer': '', 'home_page_in_toc': False, 'announcement': '⚠️The latest release refactored our HTML, so double-check your custom CSS rules!⚠️', 'use_repository_button': True, 'use_edit_page_button': True, 'use_issues_button': True}
 html_title = ''
 intersphinx_mapping = {'ebp': ['https://executablebooks.org/en/latest/', None], 'myst-parser': ['https://myst-parser.readthedocs.io/en/latest/', None], 'myst-nb': ['https://myst-nb.readthedocs.io/en/latest/', None], 'sphinx': ['https://www.sphinx-doc.org/en/master', None], 'nbformat': ['https://nbformat.readthedocs.io/en/latest', None], 'sphinx-panels': ['https://sphinx-panels.readthedocs.io/en/sphinx-book-theme/', None]}
 jupyter_cache = ''

docs/web/announcements.md

+# Announcement banners
+
+You can provide text that is shown in an "announcement" banner.
+The banner will disappear once the user scrolls down, but is styled with contrastive colors to be more noticeable.
+This can be used to draw attention to certain messages but in a way that doesn't distract from reading as the person scrolls down.
+
+To add an announcement message to your documentation, use the following configuration in `_config.yml`:
+
+```yaml
+html:
+    announcement: "My announcement!"
+```
+
+The value of `announcement` will be inserted in the top of your page.
+This can take arbitrary HTML, for example:
+
+```yaml
+html:
+    announcement: "<p class='mystyle'>Some custom HTML!</p>"
+```

jupyter_book/config.py

@@ -278,6 +278,7 @@ def yaml_to_sphinx(yaml: dict):
             # Deprecate navbar_footer_text after a release cycle
             ("extra_footer", "extra_footer"),
             ("home_page_in_toc", "home_page_in_navbar"),
+            ("announcement", "announcement"),
         ]:
             if yml_key in html:
                 theme_options[spx_key] = html[yml_key]

jupyter_book/config_schema.json

@@ -142,6 +142,9 @@
                             ]
                         }
                     }
+                },
+                "announcement": {
+                    "type": "string"
                 }
             }
         },

jupyter_book/default_config.yml

@@ -60,6 +60,7 @@ html:
   comments:
     hypothesis              : false
     utterances              : false
+  announcement              : "" # A banner announcement at the top of the site.
 
 #######################################################################################
 # LaTeX-specific settings

pyproject.toml

@@ -44,7 +44,7 @@ dependencies = [
     "sphinx-jupyterbook-latex~=0.4.6",
     "sphinx-panels~=0.6.0",
     "sphinx-thebe~=0.1.1",
-    "sphinx_book_theme~=0.1.4",
+    "sphinx_book_theme~=0.3.2",
     "sphinx_togglebutton",
     "sphinxcontrib-bibtex>=2.2.0,<=2.5.0",
     "sphinx-multitoc-numbering~=0.1.3",

tests/test_build/_toc_numbered.sphinx3.html

 <nav aria-label="Main" class="bd-links" id="bd-docs-nav">
  <div class="bd-toc-item active">
-  <ul class="nav bd-sidenav">
-   <li class="toctree-l1 current">
+  <ul class="nav bd-sidenav bd-sidenav__home-link">
+   <li class="toctree-l1 current active">
     <a class="reference internal" href="#">
      Main index
     </a>

tests/test_build/_toc_numbered.sphinx4.html

 <nav aria-label="Main" class="bd-links" id="bd-docs-nav">
  <div class="bd-toc-item active">
-  <ul class="nav bd-sidenav">
-   <li class="toctree-l1 current">
+  <ul class="nav bd-sidenav bd-sidenav__home-link">
+   <li class="toctree-l1 current active">
     <a class="reference internal" href="#">
      Main index
     </a>

tests/test_build/_toc_numbered_depth.sphinx3.html

 <nav aria-label="Main" class="bd-links" id="bd-docs-nav">
  <div class="bd-toc-item active">
-  <ul class="nav bd-sidenav">
-   <li class="toctree-l1 current">
+  <ul class="nav bd-sidenav bd-sidenav__home-link">
+   <li class="toctree-l1 current active">
     <a class="reference internal" href="#">
      Main index
     </a>

tests/test_build/_toc_numbered_depth.sphinx4.html

 <nav aria-label="Main" class="bd-links" id="bd-docs-nav">
  <div class="bd-toc-item active">
-  <ul class="nav bd-sidenav">
-   <li class="toctree-l1 current">
+  <ul class="nav bd-sidenav bd-sidenav__home-link">
+   <li class="toctree-l1 current active">
     <a class="reference internal" href="#">
      Main index
     </a>

tests/test_build/_toc_numbered_depth_parts_subset.sphinx3.html

 <nav aria-label="Main" class="bd-links" id="bd-docs-nav">
  <div class="bd-toc-item active">
-  <ul class="nav bd-sidenav">
-   <li class="toctree-l1 current">
+  <ul class="nav bd-sidenav bd-sidenav__home-link">
+   <li class="toctree-l1 current active">
     <a class="reference internal" href="#">
      Main index
     </a>

tests/test_build/_toc_numbered_depth_parts_subset.sphinx4.html

 <nav aria-label="Main" class="bd-links" id="bd-docs-nav">
  <div class="bd-toc-item active">
-  <ul class="nav bd-sidenav">
-   <li class="toctree-l1 current">
+  <ul class="nav bd-sidenav bd-sidenav__home-link">
+   <li class="toctree-l1 current active">
     <a class="reference internal" href="#">
      Main index
     </a>

tests/test_build/_toc_numbered_parts.sphinx3.html

 <nav aria-label="Main" class="bd-links" id="bd-docs-nav">
  <div class="bd-toc-item active">
-  <ul class="nav bd-sidenav">
-   <li class="toctree-l1 current">
+  <ul class="nav bd-sidenav bd-sidenav__home-link">
+   <li class="toctree-l1 current active">
     <a class="reference internal" href="#">
      Main index
     </a>

tests/test_build/_toc_numbered_parts.sphinx4.html

 <nav aria-label="Main" class="bd-links" id="bd-docs-nav">
  <div class="bd-toc-item active">
-  <ul class="nav bd-sidenav">
-   <li class="toctree-l1 current">
+  <ul class="nav bd-sidenav bd-sidenav__home-link">
+   <li class="toctree-l1 current active">
     <a class="reference internal" href="#">
      Main index
     </a>

tests/test_build/_toc_numbered_parts_subset.sphinx3.html

 <nav aria-label="Main" class="bd-links" id="bd-docs-nav">
  <div class="bd-toc-item active">
-  <ul class="nav bd-sidenav">
-   <li class="toctree-l1 current">
+  <ul class="nav bd-sidenav bd-sidenav__home-link">
+   <li class="toctree-l1 current active">
     <a class="reference internal" href="#">
      Main index
     </a>

tests/test_build/_toc_numbered_parts_subset.sphinx4.html

 <nav aria-label="Main" class="bd-links" id="bd-docs-nav">
  <div class="bd-toc-item active">
-  <ul class="nav bd-sidenav">
-   <li class="toctree-l1 current">
+  <ul class="nav bd-sidenav bd-sidenav__home-link">
+   <li class="toctree-l1 current active">
     <a class="reference internal" href="#">
      Main index
     </a>

tests/test_config/test_config_sphinx_command.txt

@@ -19,7 +19,7 @@ html_favicon = ''
 html_logo = ''
 html_sourcelink_suffix = ''
 html_theme = 'sphinx_book_theme'
-html_theme_options = {'search_bar_text': 'Search this book...', 'launch_buttons': {'notebook_interface': 'classic', 'binderhub_url': 'https://mybinder.org', 'jupyterhub_url': '', 'thebe': False, 'colab_url': ''}, 'path_to_docs': '', 'repository_url': 'https://github.com/executablebooks/jupyter-book', 'repository_branch': 'master', 'google_analytics_id': '', 'extra_navbar': 'Powered by <a href="https://jupyterbook.org">Jupyter Book</a>', 'extra_footer': '', 'home_page_in_toc': True, 'use_repository_button': False, 'use_edit_page_button': False, 'use_issues_button': False}
+html_theme_options = {'search_bar_text': 'Search this book...', 'launch_buttons': {'notebook_interface': 'classic', 'binderhub_url': 'https://mybinder.org', 'jupyterhub_url': '', 'thebe': False, 'colab_url': ''}, 'path_to_docs': '', 'repository_url': 'https://github.com/executablebooks/jupyter-book', 'repository_branch': 'master', 'google_analytics_id': '', 'extra_navbar': 'Powered by <a href="https://jupyterbook.org">Jupyter Book</a>', 'extra_footer': '', 'home_page_in_toc': True, 'announcement': '', 'use_repository_button': False, 'use_edit_page_button': False, 'use_issues_button': False}
 html_title = 'test'
 jupyter_cache = ''
 jupyter_execute_notebooks = 'auto'

tests/test_config/test_config_sphinx_command_only_build_toc_files.txt

@@ -19,7 +19,7 @@ html_favicon = ''
 html_logo = ''
 html_sourcelink_suffix = ''
 html_theme = 'sphinx_book_theme'
-html_theme_options = {'search_bar_text': 'Search this book...', 'launch_buttons': {'notebook_interface': 'classic', 'binderhub_url': 'https://mybinder.org', 'jupyterhub_url': '', 'thebe': False, 'colab_url': ''}, 'path_to_docs': '', 'repository_url': 'https://github.com/executablebooks/jupyter-book', 'repository_branch': 'master', 'google_analytics_id': '', 'extra_navbar': 'Powered by <a href="https://jupyterbook.org">Jupyter Book</a>', 'extra_footer': '', 'home_page_in_toc': True, 'use_repository_button': False, 'use_edit_page_button': False, 'use_issues_button': False}
+html_theme_options = {'search_bar_text': 'Search this book...', 'launch_buttons': {'notebook_interface': 'classic', 'binderhub_url': 'https://mybinder.org', 'jupyterhub_url': '', 'thebe': False, 'colab_url': ''}, 'path_to_docs': '', 'repository_url': 'https://github.com/executablebooks/jupyter-book', 'repository_branch': 'master', 'google_analytics_id': '', 'extra_navbar': 'Powered by <a href="https://jupyterbook.org">Jupyter Book</a>', 'extra_footer': '', 'home_page_in_toc': True, 'announcement': '', 'use_repository_button': False, 'use_edit_page_button': False, 'use_issues_button': False}
 html_title = 'My Jupyter Book'
 jupyter_cache = ''
 jupyter_execute_notebooks = 'auto'