Side notes with references to text

[amueller]

Description

Margin / sidenote content is an important part of Jupyter Book, as Tufte CSS recommends (see "Sidenotes: Footnotes and Marginal Notes"). However, the functionality is currently a bit simple, and we could improve this considerably.

This theme currently implements "margin notes" with one pattern:

```{margin}
Margin content
```

This is block-level content that behaves like an admonition, and adds the margin class, which causes it to pop out to the margin.

However, there are a few downsides to this:

• It doesn't follow the suggested structure that Tufte recommends for HTML sidenotes/margin notes
• As a result it is displayed automatically on more narrow screens, whereas Tufte recommends having it hidden by default with a click to show
• We do not implement "numbered" sidenotes, only un-numbered ones.
• We only have a block-level directive, not an inline role
• (optionally) all of these are defined in the sphinx-book-theme, but ideally these could be an independent sphinx extension so that other themes could implement support for this as well

We could address these limitations by defining a more complete set of roles/directives that address the use-cases described in Tufte.

Implementation guide

Role/directive naming + structure

Tufte uses these names for things:

• marginnotes are un-numbered notes in the margin, with no reference point in the text.
• sidenotes are numbered notes in the margin, with a corresponding number in the text.

So I think it makes sense for marginnotes to have both an inline and a block implementation, whereas sidenotes only need an inline implementation since they need some text to refer to anyway.

There's a similar implementation of this in the Jekyll Tufte Theme. In the margin notes section, they show the liquid template that is used to inject this content:

{% sidenote 'sn-id-whatever' 'This is a sidenote and *displays a superscript*'%}

{% marginnote 'mn-id-whatever' 'This is a margin note *without* a superscript' %}

We could accomplish something similar with

block-level directives

```{marginnote} Title
Content
```

inline-level roles

Some text and {marginnote}`a margin note`.

Some text and {sidenote}`a side note`.

We could auto-generate the id for each, so that users don't need to manually provide it. In the future we could explore enabling user-provided id via a pattern like

```{margin} Title
:label: my-label
Content
```

Some text and {sidenote}`"my-label" "a side note"`.

HTML / CSS implementation

Here's what Tufte CSS recommends for the in-line content:

Margin notes do not have numbered labels and so it just a matter of getting the right HTML/CSS behavior:

<label for="mn-demo" class="margin-toggle">&#8853;</label>
<input type="checkbox" id="mn-demo" class="margin-toggle"/>
<span class="marginnote">
  This is a margin note. Notice there isn’t a number preceding the note.
</span>

We might explore doing this with an <aside> element since that is semantically closer to what this is.

Side Notes have a reference number, so are a bit more complicated. They add on an extra bit of HTML to include the first label.

<label for="sn-demo"
       class="margin-toggle sidenote-number">
</label>
<input type="checkbox"
       id="sn-demo"
       class="margin-toggle"/>

If we don't require clickable links between the label and the sidenote, then we should be able to relatively easy get this to work with CSS counters and the counter-increment rule.

Basically this means some combination of:

• For the first instance of sidenote, initialize it with a CSS rule:

  counter-reset: sidenote-conuter;

• Whenever we want the label to show up, use an ::after or ::before and include something like the following:

  .sidenote::before {
      content: counter(sidenote-counter) " ";
  }

• When in subsequent sidenote instances, use a CSS rule to increment the counter:

     ::before {
       counter-increment: section; /* Increment the value of section counter by 1 */
     }

See how the Tufte HTML is structured for more reference.

Updates and tasks

[choldgraf]

Some quick ideas from what I mentioned in the other thread:

Does anybody know of a standard markdown syntax for sidebars? It exists for footnotes but I haven't seen sidebars before. Otherwise we'd need to write our own role and directive and ask people to use that

e.g. something like:

in-line with text would be {side}`my_label`

and then underneath it would be

```{side} my_label
My sidebar text
```

Alternatively, I wonder if we could just add a :label: option to the {margin} directive. Then we could do

Here's text and ref to a sidenote {ref}`mylabel`

```{margin} mylabel
Some margin text
```

And it would put the label into the text, e.g. [mylabel] ?

maybe @chrisjsewell has ideas for how we could support sidenotes w/ myst

[chrisjsewell]

FYI, semantically what you are referring to are "asides": https://www.w3schools.com/tags/tag_aside.asp

[choldgraf]

That's w3c-semantically, is it the same in "publishing" circles or in latex? Something we should try to look up as well. I did a quick search and found several references for both "aside" and for "sidenote" in the tex world.

re: getting the CSS to work, maybe if we use a reference for the aside, then at the doctree parse we could move around the aside node to come just before the paragraph with the reference in it, which would make the CSS more straightforward. If we put the node after the reference, then we'll need to find a way to move it upwards in the margin so that it lines up properly (but we'd need a way to calculate the height of the previous sibling element to do this right)

[chrisjsewell]

FYI I have added executablebooks/sphinx-panels#23.
Note this is not quite what is asked for here, because you can only have a single "aside" per paragraph, rather than the multiple one you could have with a "footnote" type approach.

[chrisjsewell]

For this particular use case, would it not be possible to literally just use the footnote syntax/directives, but then have a configuration "switch" that selects how footnotes are visualised:

• At the bottom of the page
• In the margin
• In a call-out

[choldgraf]

re: your point, one option would be to allow people to control this at the level of footnote definitions. Right now we grab all those definitions and put them at the bottom of the rendered page, but if the definition were in, say, an {aside} block then perhaps we could make it show up in the side rather than in the bottom of the page.

e.g.

[^myfootnote]: Will go at the bottom

```{aside}
[^mysidenote]: Will go to the right
```

Or we could find a way to set configurations on these, but perhaps that would be best-handled by a directive

[amueller]

I like doing it as a footnote with a configurable placement.

[choldgraf]

@chrisjsewell is the way that we handle footnote definitions (where they are all collected and placed at the bottom) hard-coded into Sphinx, or something we can configure on the parsing side?

[emdupre]

One question: Would being able to hover over the note and have it appear serve the same functionality as a side-note ? I'm thinking like here, on the first line under the "Mining Gold!" section.

We could certainly have both, but I'm wondering if they'd play similar roles!

[choldgraf]

I think they'd play similar roles, though would love to see both implemented. @rowanc1 was interested in implementing something like this on the JS as well, I believe.

[choldgraf]

I wonder if, given @najuzilu's recent experience implementing exercise and solution blocks, she'd be interested in tackling this highly-requested issue next? :-)

[choldgraf]

I added a bunch of extra information to the top comment here, to try and provide some guidance for a path forward here, and incorporating discussions we've had in other spaces.

ping @pradyunsg as well - do you think this could be helpful to do at the extension level, and then themes could provide their own (optional) support for the extension via their own CSS rules?

[AakashGfude]

Should we start experimenting on what it will look like as a new extension? I reckon the extension will have directive, role declarations, with transforms and corresponding writers to convert them to semantically meaningful representation, like aside in the case of HTML writers. And using relevant packages in case of LaTeX: https://www.overleaf.com/learn/latex/Margin_notes

Will the extension have the exact implementation recommended by Tufte, like having a show/hide button/reference when in smaller screens? Or we leave that to the theme. For example, sphinx-book-theme might want to have a font awesome icon for the button styling of margin notes when on smaller screens. We can probably have a default icon implemented in the extension, and themes can edit that according to their requirements.

[mmcky]

Should we start experimenting on what it will look like as a new extension? I reckon the extension will have directive, role declarations, with transforms and corresponding writers to convert them to semantically meaningful representation, like aside in the case of HTML writers. And using relevant packages in case of LaTeX: https://www.overleaf.com/learn/latex/Margin_notes

Will the extension have the exact implementation recommended by Tufte, like having a show/hide button/reference when in smaller screens? Or we leave that to the theme. For example, sphinx-book-theme might want to have a font awesome icon for the button styling of margin notes when on smaller screens. We can probably have a default icon implemented in the extension, and themes can edit that according to their requirements.

@AakashGfude from our discussions I think we should start building sphinx-book-components that provide support for books that include:

1. margin / aside or sidenote directives
2. part / chapter support infrastructure for numbering (and deprecate sphinx-multitoc-numbering)

I think this sort of a grouping would make sense. Let's raise this at the team meeting on Wed/Thur (AEST) as well to make sure others agree this is a good way to move this issue forward.

It would also be good if you can document where the current margin infrastructure is housed etc. Is that in sphinx-book-theme? I think we want to make sure that we aren't proliferating extensions for no benefit.

(cc: @chrisjsewell @choldgraf) What do you think about consolidating elements to support book style features in a single extension?

[choldgraf]

That sounds good to me - it would be great to see some prototypes of margin/sidenote directives.

I agree with @AakashGfude that we don't want to be too opinionated in the implementation. I think we should use the semantics and structure Tufte though, since it's a known structure by a respected authority. Maybe we should just pick some simple and clean UI that a theme developer could fancy up if they wanted to with their own CSS.

As far as being its own extension or not, I don't have strong opinions. I guess it's a question if whether we think of these two features as inherently linked (or, if they're just similar enough that it's worth combining just for simplicity).

FYI here are the relevant bits of code:

• Here is the margin directive - it is actually very simple, just wrapping the Sidebar directive to add a margin-specific class. So we might want to change this if we wanted the structure to be different
• here's the margin CSS that defines how things behave to the right.

There might be parts about the Sphinx Book Theme that we don't want to copy over - e.g., we probably don't want to assume whether a margin is even present, since some themes don't explicitly make whitespace for it. But I think we'll start figuring it out once we've got some code to work with.

[pradyunsg]

do you think this could be helpful to do at the extension level, and then themes could provide their own (optional) support for the extension via their own CSS rules?

Yes. :)

[pradyunsg]

And it may be beneficial to have the extension error out, if the theme says "I don't work with this extension" or something like that? Or... having it fallback to behaving like a .. sidebar.

[mmcky]

And it may be beneficial to have the extension error out, if the theme says "I don't work with this extension" or something like that? Or... having it fallback to behaving like a .. sidebar.

I would like something along these lines too, but will need to figure out how an extension can check for theme compatibility (as an interface of some kind).

[AakashGfude]

Great. So, as @choldgraf is indicating from his comment and @mmcky mentioned in our discussion. As a start, we should first try out implementing in sphinx-book-theme, which already has relevant bits of code. And then see if making an extra extension would make more sense.

[choldgraf]

I think that ultimately this does make sense as its own extension, so that the directives, roles, and subsequent html / latex behavior could be standardized. Then themes could define their own CSS to make the html behave as they wished. But I agree that it would be easiest to make quick progress by piggy backing on the work that is already in the book theme. I'm happy to review PRs that give this a shot in either location!