Open fbanning opened 1 year ago
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 = 5
println(a)</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.
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
@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. ```julia 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 ```julia a = 1 b = 2 a + b ``` @@
leads to this page:
The examples hopefully visually demonstrate the issues I've described above.
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\">
This is some text in a sidenote.
The styling of this sidenote is incorrect.
<code class=\"language-julia\">a = 1\nb = 2\na + b
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 div
ing the whole thing?
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)<p>
this can be addressed with CSS or removing the newline 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.
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:
@@sidenote-number
and @@sidenote
shorthands should be replaced because they only create div
s and we need different tags instead. \sidenote-number
command that creates a label
tag for the numbering in the running text,\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.)
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.
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? 🤔
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
<span>
, potentially something like <section>
which allows nested tags inside it, orso 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:
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 ?
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.
@@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?@@sidenote-number ... @@
divides the currentp
element (with content...
) and creates a newdiv
element outside of it? This works differently from what I would expect which would be a regularsup
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 thep
?Thanks for any help in advance!