Feature proposal / RFC: sidenotes

[notpushkin]

See it live: https://material-tufte.ale.sh/
Source code: https://material-tufte.ale.sh/stylesheets/tufte-sidebars.css

[squidfunk]

Excellent idea!

[notpushkin]

An example in the wild (with the Blog addon!):

Still trying to get it working with footnotes :')

[notpushkin]

Another example:

This could work pretty well as an alternative view for code annotations if implemented properly (right now this is a pile of CSS hacks making a few code blocks look like a continuous one).

UPD: see it live: https://lunni.aedge.dev/deploy/

[squidfunk]

Definitely interesting. How do you imagine this working on mobile? Does this mandate the use of toc.integrate?

[notpushkin]

@squidfunk For code blocks in particular, I'd say it can just fall back to click-to-show annotations on mobile? While I generally prefer interleaving notes with main content, breaking in the middle of a code listing might look a bit strange:

[notpushkin]

Does this mandate the use of toc.integrate?

I'd say yeah, either that or disabling TOC altogether. Unless you have any ideas how to make them work together? :-)

[squidfunk]

Disabling table of contents is probably not an option for many users and toc.integrate has several short comings, i.e. it doesn't work well for blogs (yet?) and can't be combined with section index pages. From the top of my head, mobile support and table of contents are the main two blockers that need some deep thinking before tackling sidenotes. I like the idea of sidenotes and think there's value in providing it as a feature, but it's definitely not easy to implement properly.

[notpushkin]

Let's discuss mobile support here.

From the top of my head, I see three possible uses of sidenotes:

Plain margin notes

Just some text on the margin. On mobile, those can just be inlined after the paragraph they're attached to:

Screenshot

Alternatively, Tufte CSS implements those as a ⊕ link/button inside the paragraph, but I see this as undesirable: it requires another tap on a rather small button to show content, rather than allowing to just scroll past through it. Same goes for tap-to-show footnotes.

Footnotes

Those would too look nice inlined on mobile IMHO:

Screenshot

Code annotations

Compared to footnotes, which have numbers and thus can be safely moved a bit away from the related text, code annotations are unnumbered and should occur near the line they are talking about so that it is easier for the reader to follow.

On mobile, we can just reuse the current code annotation logic with the tap-to-show button. Some alternative approaches:

• Just showing all the annotations below code block is suboptimal because code blocks that need annotations are probably long enough and user will have to scroll back and forth.
• Interleaving code with annotations (can be seen here) is hard to implement properly if we have a single <pre><code> block.

[notpushkin]

Let's discuss TOC in this thread.

I don't really see a way to integrate right-hand TOC with sidenotes cleanly.

• We could make TOC static, or fixed on the screen until it bumps into the first note. We'll need to make sure there's no note collapsing with it on the very start. (how?)

• Less complicated solution could be to allow TOC prefixing the content itself. Perhaps this could be a good option for blog posts? I'd make it opt-in though, as it only makes sense for longer posts.

Any other ideas?

[squidfunk]

1. This will not work with the current architecture (it would need to be sticky and sidenotes would need to live in the same container, which they don't. I'm not sure I can even imagine this working without making it overly complex. Code annotations are already quite complex.
2. is fundamentally different from what we have now. It's definitely possible to pull off, but I'm not sure we want to support a third ay to render the table of contents besides on the right and on the left. Thus I'd rather leave this option as an exercise to the reader 😊

Thus I'm also not really seeing it. Maybe you can fiddle around a little and see if you can pull something off that basically works. We could then discuss whether this might be a good fit integrating. At this state I'd view it as a pre-prototype.

[notpushkin]

I'll give it some more thought. Thanks for the feedback!

Perhaps there's a way to give this a tiny bit of visibility? I feel like this problem could use another pair of eyes ✨

[squidfunk]

I've pinned the discussion, maybe some other users have some ideas. In order to convert it to a feature request and consider it for implementation, we would need a solid proposal. For this to happen, some thought is necessary. To be clear: I'm not yet convinced that the mechanics generalize well enough. Happy to be convinced, though, as I like the idea.