Styling of tufte sidenotes and their numbering

[Frederik Banning]

Hey there @tlienart,

first of all: love your work on Franklin.jl, thanks for making this! :)

I use it for my personal website together with the tufte css template from FranklinTemplates.jl. A bit of tweaking here and there was necessary but it looks quite nice already. I would like to add my Julia tutorial on agent-based modelling to it but currently face some problems in using Franklin. Hope you can help me or point me in the right direction.

1. How can I write multiline sidenotes? Wrapping my sidenote in @@sidenote ... @@ only properly formats the text if I have no line-breaks in there. I've found a way to include linebreaks or even paragraphs with \\ but this is incompatible with multi-line code blocks for example. How could I work around this?
2. Why is it that @@sidenote-number ... @@ divides the current p element (with content ...) and creates a new div element outside of it? This works differently from what I would expect which would be a regular sup number at the end of the text I've wrapped. Wouldn't it make more sense to have this extra styling block as a part inside the p?

Thanks for any help in advance!

[Thibaut Lienart]

Hello @fbanning could you give me an example of content of sidenote you'd want? that would help to test a few things.

@@sidenote 
Some content here then \\
Some content on a new line and
```
a = 5
println(a)
```
@@

leads to this html (you can test that with fd2html(a_string)):

<div class="sidenote"><p>Some content here then <br />Some content on a new line and</p>
<pre><code class="language-julia">a &#61; 5
println&#40;a&#41;</code></pre></div>

which has a line break and the multiline code should be shown just fine unless you have an issue in your CSS.

Separately: if you know what target HTML you expect, it's a good idea to write your own command for this, possibly wrapping around some Franklin to do the conversion from "Franklin-Markdown" to HTML. For instance you could look at this example .

For (2) could you give an example again (possibly a string that when converted via fd2html shows the problem). One thing to note is that Franklin "fights" against Julia's base Markdown conversion which inserts <p> in wrong places. A rewrite of Franklin (Xranklin) does away with Julia's base Markdown and so fixes this stuff so I'm aware of it. But with the current version, if you give a precise example we may be able to work around it to at least get you something that works for now.

[Frederik Banning]

I've created a new Franklin page (newsite(".", template="tufte")) with unmodified CSS files to make sure this doesn't come from the changes I've made.

The following

Example page

@def title = "Tufte sandbox"
Tufte sandbox
Example 1
This is a paragraph that gets @@sidenote-number split into three pieces @@ by sidenote-number even though it should stay together.
@@sidenote

This is some text with linebreaksin a sidenote.\

This sidenote is just fine.\\

And it even allows for paragraphs via \\\\.

@@
Example 2
@@sidenote-number

This is a second paragraph that's wrapped completely in the @@sidenote-number ... @@ block to demonstrate how a code block in a sidenote messes with the sidenote style.

@@
@@sidenote

This is some text in a sidenote.\

The styling of this sidenote is incorrect.
a = 1
b = 2
a + b
@@
Example 3
@@sidenote-number

This is a third paragraph to demonstrate how code blocks are normally formatted in sidenotes which also isn't reduced to 1rem font size as usual for sidenotes.

@@
@@sidenote
a = 1
b = 2
a + b
@@

leads to this page:

The examples hopefully visually demonstrate the issues I've described above.

[Frederik Banning]

Here's the output of fd2html for the two relevant sections:

julia> fd2html("This is a paragraph that gets @@sidenote-number split into three pieces @@ by `sidenote-number` even though it should stay together.")
"<p>This is a paragraph that gets </p>\n<div class=\"sidenote-number\">split into three pieces</div>\n<p>by <code>sidenote-number</code> even though it should stay together.</p>\n"

julia> fd2html("@@sidenote
       This is some text in a sidenote.\\
       The styling of this sidenote is incorrect.
       ```julia
       a = 1
       b = 2
       a + b
       ```
       @@")
"<div class=\"sidenote\"><p>This is some text in a sidenote.<br />The styling of this sidenote is incorrect.</p>\n<pre><code class=\"language-julia\">a &#61; 1\nb &#61; 2\na &#43; b</code></pre></div>\n"

[Frederik Banning]

The splitting of the paragraphs when using @@sidenote-numbers ... @@ seems to come from the \n elements introduced between the end of the <p> and the beginning of the <div> elements.

Edit: I think that I would instead expect some output along the lines of

<p>This is a paragraph that gets <span class="sidenote-number">split into three pieces</span> by <code>sidenote-number</code> even though it should stay together.</p>\n

Which means that we do not put a div but instead a span tag on the sidenote-number block. Wouldn't that generally make more sense instead of diving the whole thing?

[Thibaut Lienart]

1. the thing about sidenote-number splitting a paragraph is expected behaviour, a paragraph always gets split by a div. A div within a p is improper HTML (on the original tufte page they do use a span)
2. yes a newline will force a <p> this can be addressed with CSS or removing the newline
3. this is purely a css issue

so I think here most of the problems seems to be tied to specific stuff around Tufte. Maybe this issue could be transferred to FranklinTemplates as a result.

For sure there may be issues with that specific template, it's a ton of work to have fully working templates so they're given as a starting point with the implicit understanding that they very much need to be fixed. That being said, in this particular case, yes it should be a span as per their CSS: https://edwardtufte.github.io/tufte-css/

Additional note: I think here the right approach would be to create a \sidenote command that inserts the relevant things so that the exact HTML is achieved, and remove the @@sidenote stuff from the template (and add your \sidenote instead)

<p>
One of the most distinctive features of Tufte’s style is his extensive use of sidenotes.
<label for="sn-extensive-use-of-sidenotes" class="margin-toggle sidenote-number"></label><input type="checkbox" id="sn-extensive-use-of-sidenotes" class="margin-toggle"><span class="sidenote">This is a sidenote.</span>
Sidenotes are like footnotes, except they don’t force the reader to jump their eye to the bottom of the page, but instead display off to the side in the margin. Perhaps you have noticed their use in this document already. You are very astute.
</p>

the whole bit with label can be made into a command pretty easily.

[Frederik Banning]

Awesome, thanks for the insights and digging up the example html from the tufte-css repo.

Replacing the @@sidenote stuff in the tufte template seems the right way to go so that it's a bit more in line with what users might expect from that template.

To sum up how I understood your suggestions:

• The currently used @@sidenote-number and @@sidenote shorthands should be replaced because they only create divs and we need different tags instead.
• We replace these with two new commands
  1. a \sidenote-number command that creates a label tag for the numbering in the running text,
  2. a \sidenote command that creates a span for the actual sidenote content.

Did I get this right?

Defining a \sidenote command should be easy enough, I suppose. I just need to read up on how these custom commands actually work in Franklin. :D (And I really hope that I don't need to dig into how all these responsive design things work to account for different window sizes and so on.)

[Frederik Banning]

OK, this actually seems to be a lot simpler than I expected.

Using just a single command \sidenote we can automatically create everything.

\newcommand{\sidenote}[1]{
  ~~~<label class="margin-toggle sidenote-number"></label>
  <input class="margin-toggle" type="checkbox">
  <span class="sidenote">~~~
  #1
  ~~~</span>~~~
}

This creates the following output:

Correct placement of the sidenotes also seems to be done automatically! Nice. :)

Edit: Updated the command to my current iteration.

[Frederik Banning]

So I've played around a bit with the command and it seems that it does mostly what it's supposed to do. Except for the code block case:

\sidenote{This is some text in a sidenote.
  ```julia
  a = 1
  b = 2
  a + b
  ```
}

This generally produces the correct output but after the first paragraph it moves all the remaining content of the sidenote into the main body of the article.

Manually manipulating the generated HTML file and moving the pre block into the sidenote span produces the correct result.

Do you know what's going on here? 🤔

[Frederik Banning]

OK, I think I understand now. Franklin generates <p>, <pre> , etc. tags for every paragraph and piece of markdown (of course it does...). The problem is that the HTML parser (or maybe just the browser?) doesn't consider <span><p></p></span> valid HTML because it considers a <span> block to just mark up phrasing content. So it automatically reinterprets the resulting block as <span></span><p></p> (or <span></span><pre></pre> in the case of code blocks).

Having played around with this for an hour or so now, I think possible solutions would be to

1. ditch the idea of multi-paragraph sidenotes altogether (which would be a real shame),
2. use another HTML element than <span>, potentially something like <section> which allows nested tags inside it, or
3. change something inside Franklin so that it can deal with multi-paragraph sidenotes.

[Thibaut Lienart]

so the main problem in your case is really the <pre> thing which isn't allowed in a <span> as you indicated with the Browser pushing it out; the rest is more or less "ok" since using <br> in a span is fine (might require some CSS but it's valid html).

I had a look around and it turns out other people have thought about this a bit: notably https://gwern.net/sidenote#tufte-css and this is also nice https://scripter.co/sidenotes-using-only-css/ ; two takeaways:

• it's actually not entirely trivial
• there's a js script mentioned in the gwern article that I haven't tried but that seems to allow multi-paragraph notes since there's an example with a blockquote in there

My summary even though that might seem lame: if you don't often need to put code blocks in sidenotes maybe don't do that and just use <br> (\\)? if you do often need to have code blocks in side note then maybe check out if you could adapt sidenotes.js ?