NEW: Add sidenote and marginnote syntax

docs/conf.py

@@ -117,6 +117,7 @@
     "use_issues_button": True,
     "use_repository_button": True,
     "use_download_button": True,
+    "use_sidenotes": True,
     "logo_only": True,
     "show_toc_level": 2,
     "announcement": (

docs/content-blocks.md

@@ -85,32 +85,87 @@ but I'll stop here.
 ````
 `````
 
-## Sidebars
+(margin:sidenote)=
+## Sidenotes and marginnotes
+
+This theme has support for [Tufte-stype margin / side notes](https://edwardtufte.github.io/tufte-css/).
+
+Sidenotes are numbered, and behave like footnotes, except they live in the margin and don’t force the reader to jump their eye to the bottom of the page.
+For example, here is a sidenote[^ex].
+On narrow screens, sidenotes are hidden until a user clicks the number.
+If you're on a mobile device, try clicking the sidenote number above.
+
+[^ex]: Here's my sidenote text!
+
+    On narrow screens, this text won't show up unless you click the superscript number!
+
+Marginnotes are not numbered, but behave the same way as sidenotes.
+On mobile devices a symbol will be displayed that will display the marginnote when clicked[^exmn].
+For example, there's a marginnote in the previous sentence, and you should see a symbol show to display it on mobile screens.
+
+[^exmn]: {-} This is a margin note. Notice there isn’t a number preceding the note.
+
+:::{seealso}
+Sidenotes and marginnotes are inline content - you cannot use block-level content inside of these notes.
+If you'd like to use block-level content in the margins, see [](margin:block).
+:::
+
+### Activate sidenotes and marginnotes
+
+The theme activates sidenotes and marginnotes by over-riding footnote syntax to instead exist in the margin.
+
+To convert your footnotes to *instead* be sidenotes/marginnotes, use this configuration:
+
+```python
+html_theme_options = {
+  ...
+  "use_sidenotes": True,
+  ...
+}
+```
+
+This will turn your **footnotes** into **sidenotes** or **marginnotes**.
+
+### Create a sidenote
+
+For example, the following sentence defines a sidenote and its respective content:
 
-There are two different kinds of sidebar-like content in `sphinx-book-theme`,
-typical `{sidebar}` directives, as well as a theme-specific `{margin}` directive.
-This section covers both. Both allow you to place extra content
-separately from your main content.
+```markdown
+Here's my sentence and a sidenote[^sn1].
 
-```{tip}
-Sidebar content will generally overlap with the white space where your site's
-table of contents lives. When the reader scrolls sidebar content into view, the
-right TOC should hide itself automatically.
+[^sn1]: And here's my sidenote content.
 ```
 
-### Margin content
+Here's my sentence and a sidenote[^sn1].
 
-You can specify content that should exist in the right margin. This will behave
-like a regular sidebar until the screen hits a certain width, at which point this
-content will "pop out" to the right white space.
+[^sn1]: And here's my sidenote content.
 
-There are two ways to add content to the margin: via the `{margin}` directive, and via adding CSS classes to your own content.
+### Create a marginnote
 
-#### Use a `{margin}` directive to add margin content
+Marginnotes are defined by adding `{-}` at the beginning of the content block.
+For example, the following syntax defines a marginnote:
 
-The `{margin}` directive allows you to create margin content with your own title and content block.
+```markdown
+Here's my sentence and a marginnote[^mn1].
+
+[^mn1]: {-} And here's my marginnote content.
+```
+
+Here's my sentence and a marginnote[^mn1].
+
+[^mn1]: {-} And here's my marginnote content.
+
+
+(margin:block)=
+## Block margin content with the `{margin}` directive
+
+The `{margin}` directive allows you to create block-level margin content with an optional title.
 It is a wrapper around the Sphinx `{sidebar}` directive, and largely does its magic via CSS classes (see below).
 
+:::{seealso}
+If you'd like in-line margin content with numbered references, see [](margin:sidenote).
+:::
+
 Here's how you can use the `{margin}` directive:
 
 ```{margin} **Here is my margin content**
@@ -123,7 +178,39 @@ Here is my margin content, it is pretty cool!
 ```
 ````
 
-#### Use CSS classes to add margin content
+## Figure captions in the margin
+
+You can configure figures to use the margin for captions.
+Here is a figure with a caption to the right.
+
+```{figure} images/cool.jpg
+---
+width: 60%
+figclass: margin-caption
+alt: My figure text
+name: myfig5
+---
+And here is my figure caption, if you look to the left, you can see that COOL is in big red letters. But you probably already noticed that, really I am just taking up space to see how the margin caption looks like when it is really long :-).
+```
+
+And the text that produced it:
+
+````
+```{figure} images/cool.jpg
+---
+width: 60%
+figclass: margin-caption
+alt: My figure text
+name: myfig5
+---
+And here is my figure caption, if you look to the left, you can see that COOL is in big red letters. But you probably already noticed that, really I am just taking up space to see how the margin caption looks like when it is really long :-)
+```
+````
+
+We can reference the figure with {ref}`this reference <myfig5>`. Or a numbered reference like
+{numref}`myfig5`.
+
+### CSS classes for custom margin content
 
 You may also directly add CSS classes to elements on your page in order to make them behave like margin content.
 To do so, add the `margin` CSS class to any element on the page.
@@ -174,65 +261,10 @@ And here is my figure caption
 We can reference the figure with {ref}`myfig4`. Or a numbered reference like
 {numref}`myfig4`.
 
-#### Figure captions in the margin
-
-You can configure figures to use the margin for captions.
-Here is a figure with a caption to the right.
-
-```{figure} images/cool.jpg
----
-width: 60%
-figclass: margin-caption
-alt: My figure text
-name: myfig5
----
-And here is my figure caption, if you look to the left, you can see that COOL is in big red letters. But you probably already noticed that, really I am just taking up space to see how the margin caption looks like when it is really long :-).
-```
-
-And the text that produced it:
-
-````
-```{figure} images/cool.jpg
----
-width: 60%
-figclass: margin-caption
-alt: My figure text
-name: myfig5
----
-And here is my figure caption, if you look to the left, you can see that COOL is in big red letters. But you probably already noticed that, really I am just taking up space to see how the margin caption looks like when it is really long :-)
-```
-````
-
-We can reference the figure with {ref}`this reference <myfig5>`. Or a numbered reference like
-{numref}`myfig5`.
-
-### Content sidebars
-
-Content sidebars exist in-line with your text, but allow the rest of the
-page to flow around them, rather than moving to the right margin.
-To add content sidebars, use this syntax:
-
-````{sidebar} **My sidebar title**
-```{note}
-Here is my sidebar content, it is pretty cool!
-```
-![](images/cool.jpg)
-````
-
-Note how the content wraps around the sidebar to the right.
-However, the sidebar text will still be in line with your content. There are
-certain kinds of elements, such as "note" blocks and code cells, that may
-clash with your sidebar. If this happens, try using a `{margin}` instead.
-
-````
-```{sidebar} **My sidebar title**
-Here is my sidebar content, it is pretty cool!
-```
-````
 
 ### Adding content to margins and sidebars
 
-Sidebar/margin content can include all kinds of things, such as code blocks:
+Margin content can include all kinds of things, such as code blocks:
 
 ````{margin} Code blocks in margins
 ```python
@@ -266,6 +298,7 @@ Wow, a note with an image in a margin!
 ````
 `````
 
+
 ## Full-width content
 
 Full-width content extends into the right margin, making it stand out against
@@ -292,3 +325,28 @@ If you are using a Jupyter Notebook as inputs to your documentation using the
 [MyST-NB extension](https://myst-nb.readthedocs.io/en/latest/), you can trigger
 this behavior with a code cell by adding a `full-width` tag to the cell.
 ```
+
+
+## Sidebars
+
+Content sidebars exist in-line with your text, but allow the rest of the
+page to flow around them, rather than moving to the right margin.
+To add content sidebars, use this syntax:
+
+````{sidebar} **My sidebar title**
+```{note}
+Here is my sidebar content, it is pretty cool!
+```
+![](images/cool.jpg)
+````
+
+Note how the content wraps around the sidebar to the right.
+However, the sidebar text will still be in line with your content. There are
+certain kinds of elements, such as "note" blocks and code cells, that may
+clash with your sidebar. If this happens, try using a `{margin}` instead.
+
+````
+```{sidebar} **My sidebar title**
+Here is my sidebar content, it is pretty cool!
+```
+````

docs/reference/special-theme-elements.md

@@ -255,6 +255,18 @@ And here is my figure caption, if you look to the left, you can see that COOL is
 This note should not overlap with the margin caption!
 :::
 
+## Sidenotes and marginnotes
+
+Here's a sentence[^sn1] with multiple [^sn2] sidenotes.
+
+[^sn1]: Test sidenote 1.
+[^sn2]: Test sidenote 2.
+
+Here's a sentence[^mn1] with multiple marginnotes[^mn2].
+
+[^mn1]: {-} Test marginnote 1.
+[^mn2]: {-} Test marginnote 2.
+
 ## Nested admonitions
 
 These aren't theme-specific, but we still show below to make sure they work.

src/sphinx_book_theme/__init__.py

@@ -5,13 +5,15 @@
 from functools import lru_cache
 
 from docutils.parsers.rst.directives.body import Sidebar
-from docutils import nodes
+from docutils import nodes as docutil_nodes
 from sphinx.application import Sphinx
 from sphinx.locale import get_translation
 from sphinx.util import logging
 
+from .nodes import SideNoteNode
 from .header_buttons import prep_header_buttons, add_header_buttons
 from .header_buttons.launch import add_launch_buttons
+from ._transforms import HandleFootnoteTransform
 
 __version__ = "0.3.0.rc2"
 """sphinx-book-theme version"""
@@ -43,7 +45,7 @@ def add_metadata_to_page(app, pagename, templatename, context, doctree):
     # Add a shortened page text to the context using the sections text
     if doctree:
         description = ""
-        for section in doctree.traverse(nodes.section):
+        for section in doctree.traverse(docutil_nodes.section):
             description += section.astext().replace("\n", " ")
         description = description[:160]
         context["page_description"] = description
@@ -177,6 +179,9 @@ def setup(app: Sphinx):
     app.connect("html-page-context", add_metadata_to_page)
     app.connect("html-page-context", hash_html_assets)
 
+    # Nodes
+    SideNoteNode.add_node(app)
+
     # Header buttons
     app.connect("html-page-context", prep_header_buttons)
     app.connect("html-page-context", add_launch_buttons)
@@ -186,6 +191,9 @@ def setup(app: Sphinx):
     # Directives
     app.add_directive("margin", Margin)
 
+    # Post-transforms
+    app.add_post_transform(HandleFootnoteTransform)
+
     # Update templates for sidebar
     app.config.templates_path.append(os.path.join(theme_dir, "components"))
 

src/sphinx_book_theme/_transforms.py

@@ -0,0 +1,49 @@
+from sphinx.transforms.post_transforms import SphinxPostTransform
+from typing import Any
+from docutils import nodes as docutil_nodes
+from .nodes import SideNoteNode
+
+
+class HandleFootnoteTransform(SphinxPostTransform):
+
+    default_priority = 1
+
+    def apply(self, **kwargs: Any) -> None:
+        theme_options = self.env.config.html_theme_options
+        if theme_options.get("use_sidenotes", False) is True:
+            for node in self.document.traverse(docutil_nodes.footnote_reference):
+                parent = None
+                for ftnode in self.document.traverse(docutil_nodes.footnote):
+                    # matching the footnote reference with footnote
+                    if (
+                        len(ftnode.attributes["backrefs"])
+                        and ftnode.attributes["backrefs"][0]
+                        == node.attributes["ids"][0]
+                    ):
+                        parent = ftnode.parent
+                        text = ftnode.children[1].astext()
+
+                        sidenote = SideNoteNode()
+                        para = docutil_nodes.inline()
+                        if text.startswith("{-}"):
+                            # marginnotes
+                            para.attributes["classes"].append("marginnote")
+                            para.append(docutil_nodes.Text(text.replace("{-}", "")))
+
+                            sidenote.attributes["names"].append("marginnote-role")
+                        else:
+                            # sidenotes
+                            label = ftnode.children[0].astext()
+
+                            superscript = docutil_nodes.superscript("", label)
+                            para.attributes["classes"].append("sidenote")
+                            para.extend([superscript, docutil_nodes.Text(text)])
+
+                            sidenote.attributes["names"].append(
+                                f"sidenote-role-{label}"
+                            )
+                            sidenote.append(superscript)
+                        node.replace_self([sidenote, para])
+                        break
+                if parent:
+                    parent.remove(ftnode)

src/sphinx_book_theme/assets/scripts/index.js

@@ -133,6 +133,8 @@ var initTocHide = () => {
   // Set up the intersection observer to watch all margin content
   let tocObserver = new IntersectionObserver(hideTocCallback);
   const selectorClasses = [
+    "marginnote",
+    "sidenote",
     "margin",
     "margin-caption",
     "full-width",