Jupyter-book: Side notes with references to text

[amueller]

I think it would be great to allow side-notes to refer to the text in the same way footnotes do, like so:

Some discussion here where @choldgraf suggest two ways to add these labels, either by extending margin with a :label: directive or by adding a new command side (if I understand correctly).

[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 https://github.com/executablebooks/sphinx-panels/issues/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.

```{aside} ```

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? :-)