executablebooks · choldgraf · Feb 16, 2023 · Feb 8, 2023 · Feb 8, 2023 · Feb 9, 2023
diff --git a/.github/workflows/lighthouserc.json b/.github/workflows/lighthouserc.json
@@ -9,9 +9,9 @@
     },
     "assert": {
       "assertions": {
-        "categories:performance": ["error", { "minScore": 0.84 }],
-        "categories:accessibility": ["error", { "minScore": 0.84 }],
-        "categories:best-practices": ["error", { "minScore": 0.84 }]
+        "categories:performance": ["error", { "minScore": 0.8 }],
+        "categories:accessibility": ["error", { "minScore": 0.8 }],
+        "categories:best-practices": ["error", { "minScore": 0.8 }]
       }
     }
   }

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1 +1 @@
-See [the contributing documentation](./docs/contributing/index.md).
+See [the contributing documentation](https://sphinx-book-theme.readthedocs.io/en/stable/contributing/index.html).
diff --git a/docs/_static/logo-square.png b/docs/_static/logo-square.png
diff --git a/docs/_static/logo-wide-dark.svg b/docs/_static/logo-wide-dark.svg
diff --git a/docs/_templates/sections/header.html b/docs/_templates/sections/header.html
diff --git a/docs/_templates/test.html b/docs/_templates/test.html
@@ -0,0 +1,5 @@
+{# This is a test template to try out insertion in the header.
+   You can un-comment the line that adds this to our header in `conf.py`
+#}
+<button>Test button 1</button>
+<button>Test button 2</button>
diff --git a/docs/customize/custom-css.md → docs/components/custom-css.md b/docs/customize/custom-css.md → docs/components/custom-css.md
diff --git a/docs/customize/download.md → docs/components/download.md b/docs/customize/download.md → docs/components/download.md
diff --git a/docs/components/index.md b/docs/components/index.md
@@ -0,0 +1,10 @@
+# Component customization
+
+Components are specific UI elements that you can control with configuration.
+
+```{toctree}
+logo
+download
+source-files
+custom-css
+```
diff --git a/docs/components/logo.md b/docs/components/logo.md
@@ -0,0 +1,7 @@
+
+(sidebar-primary:logo)=
+# Logo and branding
+
+You can customize the logo, title, and favicon of your site.
+
+This theme uses the same configuration as the `pydata-sphinx-theme`, so refer to {external:doc}`the PyData Sphinx Theme branding documentation <user_guide/branding>`.
diff --git a/docs/customize/source-files.md → docs/components/source-files.md b/docs/customize/source-files.md → docs/components/source-files.md
@@ -1,5 +1,5 @@
 (customize:source-files)=
-# Add buttons to link to your source
+# Buttons that link to source files
 
 There are a collection of buttons that you can use to link back to your source
 repository. This lets users browse the repository, or take actions like suggest

diff --git a/docs/conf.py b/docs/conf.py
@@ -121,19 +121,30 @@
     "use_repository_button": True,
     "use_download_button": True,
     "use_sidenotes": True,
-    "logo": {
-        "text": html_title,
-    },
     "show_toc_level": 2,
     "announcement": (
         "⚠️The latest release refactored our HTML, "
         "so double-check your custom CSS rules!⚠️"
     ),
+    "logo": {
+        "image_dark": "_static/logo-wide-dark.svg",
+    }
     # For testing
     # "use_fullscreen_button": False,
     # "home_page_in_toc": True,
     # "extra_footer": "<a href='https://google.com'>Test</a>",  # DEPRECATED KEY
     # "show_navbar_depth": 2,
+    # Testing layout areas
+    # "navbar_start": ["test.html"],
+    # "navbar_center": ["test.html"],
+    # "navbar_end": ["test.html"],
+    # "footer_start": ["test.html"],
+    # "footer_end": ["test.html"]
+}
+
+# sphinxext.opengraph
+ogp_social_cards = {
+    "image": "_static/logo-square.png",
 }
 
 # -- ABlog config -------------------------------------------------

diff --git a/docs/content-blocks.md → docs/content/content-blocks.md b/docs/content-blocks.md → docs/content/content-blocks.md
@@ -158,7 +158,7 @@ Here is a figure with a caption to the right.
 ::::{example}
 :no-container:
 
-```{figure} images/cool.jpg
+```{figure} ../images/cool.jpg
 ---
 width: 60%
 figclass: margin-caption
@@ -199,7 +199,7 @@ some vertical space to see better.
 :no-container:
 :reverse:
 
-```{figure} images/cool.jpg
+```{figure} ../images/cool.jpg
 ---
 figclass: margin
 alt: My figure text
@@ -237,7 +237,7 @@ print("here is some python")
 ````{margin} **Notes in margins**
 ```{note}
 Wow, a note with an image in a margin!
-![](images/cool.jpg)
+![](../images/cool.jpg)
 ```
 ````
 `````
@@ -256,7 +256,7 @@ To add content sidebars, use this syntax:
 ```{note}
 Here is my sidebar content, it is pretty cool!
 ```
-![](images/cool.jpg)
+![](../images/cool.jpg)
 ````
 `````
 

diff --git a/docs/content/index.md b/docs/content/index.md
@@ -0,0 +1,9 @@
+# Content and formatting
+
+These sections describe content-specific customization and formatting.
+
+```{toctree}
+content-blocks
+notebooks
+launch
+```
diff --git a/docs/launch.md → docs/content/launch.md b/docs/launch.md → docs/content/launch.md
diff --git a/docs/notebooks.md → docs/content/notebooks.md b/docs/notebooks.md → docs/content/notebooks.md
@@ -22,7 +22,7 @@ This page demonstrates some extra functionality that works with this theme.
 
 As it is markdown, you can embed images, HTML, etc into your posts!
 
-![](./images/cool.jpg)
+![](../images/cool.jpg)
 
 You an also $add_{math}$ and
 

diff --git a/docs/contributing/index.md b/docs/contributing/index.md
@@ -3,7 +3,7 @@
 Thank you for being interested in contributing to the `sphinx-book-theme`! You
 are awesome ✨.
 
-This project follows the Executable Books Project [contribution guidelines](https://executablebooks.org/en/latest/contribute.html).
+This project follows the Executable Books Project [contribution guidelines](https://executablebooks.org/en/latest/contribute).
 It contains information about our conventions around coding style, pull request workflow, commit messages and more.
 
 The rest of these sections contain information about developing the `sphinx-book-theme` specifically.

diff --git a/docs/customize/header.md b/docs/customize/header.md
diff --git a/docs/index.md b/docs/index.md
@@ -30,7 +30,7 @@ A Sphinx theme with a clean design, support for interactive content, and a moder
 [Visual classes designed for Jupyter Notebooks](reference/notebooks)
 : Cell inputs, outputs, and interactive functionality are all supported.
 
-[Launch buttons for online interactivity](launch)
+[Launch buttons for online interactivity](content/launch)
 : For pages that are built with computational material, connect your site to an online BinderHub for interactive content.
 
 [Bootstrap 5](https://getbootstrap.com/docs/5.0/getting-started/introduction/)
@@ -52,19 +52,20 @@ The following topic areas will help you understand and use the theme.
 :caption: Topic Areas
 
 tutorials/get-started
-customize/index
-content-blocks
-notebooks
-launch
+content/index
+sections/index
+components/index
+reference
 contributing/index
+changelog
 ```
 
-# Reference pages
+# Example pages
 
-Reference pages demonstrate the visual look of this theme.
+Examples pages demonstrate the visual look of this theme.
 
 ```{toctree}
-:caption: Reference
+:caption: Example pages
 :maxdepth: 2
 
 reference/kitchen-sink/index
@@ -75,7 +76,6 @@ reference/thebe
 reference/blog
 reference/api-numpy
 reference/comments
-changelog
 ```
 
 # Inspiration

diff --git a/docs/customize/index.md → docs/reference.md b/docs/customize/index.md → docs/reference.md
@@ -1,10 +1,11 @@
-# Customization
 
-These sections describe a few ways that you may customize the look and feel of your theme.
+# Reference of theme options
 
-## Theme options
+The following theme-specific options are available via `html_theme_options`.
 
-The following options are available via `html_theme_options`
+```{admonition} See the PyData Theme as well
+These are **in addition to** all of the {external:doc}`options available in the PyData Sphinx Theme <user_guide/index>`.
+```
 
 ```{list-table}
 :widths: 10 5 40
@@ -49,18 +50,3 @@ The following options are available via `html_theme_options`
   - str
   - The text to be displayed with the in-page TOC (`Contents` is default)
 ```
-
-## Customization Topics
-
-The following sections describe a few ways to customize the theme in more depth.
-
-```{toctree}
-sidebar-primary.md
-sidebar-secondary.md
-footer-content.md
-announcements.md
-header.md
-download.md
-source-files.md
-custom-css.md
-```
diff --git a/docs/customize/announcements.md → docs/sections/announcements.md b/docs/customize/announcements.md → docs/sections/announcements.md
diff --git a/docs/customize/footer-content.md → docs/sections/footer-content.md b/docs/customize/footer-content.md → docs/sections/footer-content.md
@@ -1,4 +1,4 @@
-# Customize the content footer
+# Content footer
 
 There is a content footer that spans the width of the page, and is visibile when you scroll to the bottom of the content.
 

diff --git a/docs/sections/footer.md b/docs/sections/footer.md
@@ -0,0 +1,21 @@
+# Page footer
+
+The page footer spans the entire width of the page, and is only visible once you scroll to the end of the article's content.
+
+By default, it is empty and not visible.
+However, there are two configuration points where you can add items to your footer:
+
+`html_theme_options["footer_start"]` accepts a list of HTML templates that will be placed at the beginning (left on most screens) of the footer.
+
+`html_theme_options["footer_start"]` accepts a list of HTML templates that will be placed at the end (right on most screens) of the footer.
+
+For example, the configuration below assumes there is a template at `_templates/test.html`.
+It adds the `_templates` folder to Sphinx's templates path, and adds the template to both the start and end section of the footer.
+
+```python
+templates_path = ["_templates"]
+html_theme_options = {
+  "footer_start": ["test.html"],
+  "footer_end": ["test.html"]
+}
+```
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		See [the contributing documentation](./docs/contributing/index.md).
		See [the contributing documentation](https://sphinx-book-theme.readthedocs.io/en/stable/contributing/index.html).