6 ms·

Show HN: A new way to do footnotes

59 points by breck 4y ago

woodruffw 4y ago
At the risk of Dropboxing myself: what is the advantage of this over the existing Markdown syntax for footnotes[1]? It looks very similar, but with a harder to parse grammar. [1]: https://www.markdownguide.org/extended-syntax/ https://www.markdownguide.org/extended-syntax/
- SPBS 4y ago
  it looks like it aggregates all footnote definitions into one where it can be printed with the keyword 'notes' (hardcoding? too clever? what if you want to separate footnotes?)
  - reagle 4y ago
    I can’t see what this offers over pandoc markdown or it’s successor: https://htmlpreview.github.io/?https://github.com/jgm/djot/blob/master/doc/syntax.html#footnote-reference https://htmlpreview.github.io/?https://github.com/jgm/djot/b...
    - pbronez 4y ago
      Shot is new to me, thanks for sharing. Looks like a nice iteration on CommonMark. I’ve preferred Asciidoc for its availability to handle complex nested headers and internal links; djot’s custom attributes and local-first link parsing might handle that well. https://djot.net https://djot.net
- tux 4y ago
  WOW I didn't even know markdown has footnotes will definantly come in handy for one of my projects. Thank you!
  - bmacho 4y ago
    It doesn't have footnotes. Some supersets do.
    - woodruffw 4y ago
      Right, but it's worth noting that those supersets are very common. I'd say it's actually less common to run into a "barebones" Markdown implementation these days than to run into a GFM or close-to-GFM one.
      - deleted 4y ago
        [deleted]
      - deleted 4y ago
        [deleted]
    - teekert 4y ago
      Yes, for example in Hugo [0] I can do this: This is some text with a footnote.[^1] [^1]: And that's the footnote. [0] https://gohugo.io/ https://gohugo.io/
- breck 4y ago
  > At the risk of Dropboxing myself This made me laugh. I appreciate you. > but with a harder to parse grammar Grammar is actually quite simple once you've mastered the Grammar language (https://pldb.com/languages/grammar.html https://pldb.com/languages/grammar.html) which has almost no documentation and is full of bugs. > what is the advantage of this over the existing Markdown syntax for footnotes[1] I can't speak definitively yet. I think it will be better but I need to use it for a few months to be sure. There are some subtle things I think will be important.
  - woodruffw 4y ago
    Thank you for sharing that! In case I came across as overly negative: I think the overall syntax and project here are very cool. I’ll be following your work!
sillysaurusx 4y ago
I like the URL syntax. It's a clean separation between typing a sentence and attaching a link within that sentence. Nicely done.
chrismorgan 4y ago
I’ve been designing a lightweight markup language of my own in recent months, and yesterday I finally settled on a syntax that I like for notes: links (which must always be delimited in my language), but with a leading caret, which will never be present in properly-serialised URLs. (The URL ^x should be encoded %5Ex—the URL parser will accept the caret, but it’s marked as invalid if anyone cares, and the serialiser would turn it into %5E.) This makes perfect sense, because notes semantically really are links from one piece of content to another. My URLs must always be delimited in angle brackets <…>, and links can be either <url> or [contents <url>]. (I haven’t settled on a syntax I like for reference-style links.) This fits in very nicely with caret starting note references. You can have [spanned notes <^…>] and spanless notes<^…>. (I also reckon on the identifier being optional, so that <^> would be valid, just using the next note body.) This syntax is generically useful for sidenotes, footnotes, endnotes and other presentations of notes—in general, I reckon note presentation should be a presentational rather than a content concern. (Aside: what people on the web call “footnotes” are almost always actually endnotes. Endnotes are typically ergonomically poor in both print and screen media. Something along the lines of proper footnotes or inline-expandable notes mostly requires JavaScript, though with effort, restrictions about whether the content can contain blocks, and perhaps careful tip-toeing around HTML parser implementation details (or deliberately using XML syntax if you’re bold enough) and a mild disregard for nominal validity, you can do it even semantically reasonably without JavaScript.) I reckon most notes should be spanned. To demonstrate what I mean, https://chrismorgan.info/blog/rust-ownership-the-hard-way/ https://chrismorgan.info/blog/rust-ownership-the-hard-way/ shows three types of sidenotes: spanned with an inline source marker, unspanned with an inline source marker, and full block asides which are unspanned. To see my vision most clearly you’ll need a large enough viewport; on small viewports, I currently have the notes inline, with the third type aside, and I’m not happy with the in-flow placement of the asides, which is mostly a paragraph or so above the ideal place, but wanted it to all be pure CSS. Then I started wondering, how many potentially viable characters are there like this, that can’t appear at the start of properly-serialised URLs? Could they be purpose for something else? You start with all Unicode scalar values, then remove (a) all URL code points <https://url.spec.whatwg.org/#url-code-points https://url.spec.whatwg.org/#url-code-points>, because they’re valid in URLs; (b) C0 and C1 control codes because non-printables is an extremely terrible idea for normal people; (c) `#`, as it’s used to begin fragments; (d) `%`, as it’s used for percent-encoding bytes. This leaves: "<>[\]^`{|} and space. Most of them would be a bad idea for various reasons, even if they’d work; ^ and | are the only two that seem reasonable to me. So, ^ for notes. Haven’t thought of anything that fits similarly that pipe could certainly be used for. Could possibly use it for reference-style links, but that’d still be clunky (I would like to support […] matching, not needing [… <|refname>)).
iprathik 4y ago
Clicking on the number should ideal take me to footnote but it isn't. Instead its redirecting to a different page taking about scroll
- CGamesPlay 4y ago
  Yeah, possibly demo broken, but I don't understand how this is supposed to be a new way to do footnotes at all. Looks like a broken Markdown footnote to me.
- breck 4y ago
  Ah that is a bug with `try.scroll.pub`. That app was sort of hacked together a long time ago and is due for a cleanup. Sorry about that. https://github.com/breck7/tryscroll/issues/3 https://github.com/breck7/tryscroll/issues/3
verdagon 4y ago
Anyone interested in footnotes might like the way we do it on the Vale site, for example: https://verdagon.dev/blog/making-regions-part-1-human-factor https://verdagon.dev/blog/making-regions-part-1-human-factor Some nice things: * The footnotes are off to the side, so it's closer to the text that mentions it and it doesn't interrupt the flow of the main text. * It uses colors, so it's pretty fast to visually jump to the right one. * We keep the numbers too, for colorblind folks (and those using blue-light filters like f.lux) * It works without javascript! Our markdown->html renderer makes this happen by slicing up the page horizontally, one slice per header. Each slice then has a wide left column for the main text, and a narrow right column for the footnotes. Then if the user happens have javascript enabled, it position:absolute's the footnotes and lines them up a little more precisely with where they're mentioned.
- AB1908 4y ago
  You may want to explore Tufte CSS. My own article about footnotes/sidenotes: https://ab1908.github.io/2021/08/24/footnotes-in-web-content.html https://ab1908.github.io/2021/08/24/footnotes-in-web-content...
  - verdagon 4y ago
    Stellar article! Was definitely worth a read. The sidenote styles are particularly ingenious, I remember trying to get float+clear to work for this and never could, but looks like it's doable!
    - AB1908 4y ago
      Glad you liked it! I'm amazed that you liked it cause it was my first semi-serious blog post haha.
  - breck 4y ago
    Oh this is beautiful. Thanks for the link.
    - 4y ago
acqbu 4y ago
Breck, you're a good programmer, just like Terry A Davis!
- breck 4y ago
  How dare you call me only a “good” Programmer. - Sent from TempleOS
ajnin 4y ago
My favorite way is how French website "Le Monde Diplomatique" does it : the footnotes appear at the bottom of the screen in context as you scroll so that only those referred in the currently visible text are displayed. It avoids awkwardly clicking on tiny superscript numbers and annoyingly scrolling back and forth between text and footnotes. For an example : https://www.monde-diplomatique.fr/2021/01/PIGEAUD/62633 https://www.monde-diplomatique.fr/2021/01/PIGEAUD/62633
- yinyang_in 4y ago
  this is beautiful implementation. Would be nice to see how implementation was done ?
  - jer0me 4y ago
    Perhaps using Intersection Observers: https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API https://developer.mozilla.org/en-US/docs/Web/API/Intersectio...
- malshe 4y ago
  This is fantastic! Dirk Eddelbuettel and Jonathan Gilligan have an R package (https://cran.r-project.org/web/packages/tint/vignettes/tintHtmlIntro.html https://cran.r-project.org/web/packages/tint/vignettes/tintH...) that shows footnotes and many other objects in the sidetones. I like that format as well. But it is static and doesn't't change dynamically like this one in the French website you have linked to.
richsu-ca 4y ago
Something different. I have been using Markdown Footnotes extension [1] and found its syntax to be natural to Markdown. Here's the same sample as OP in Markdown Footnotes syntax. There is a link to the rendered page [2]. https://gist.githubusercontent.com/richsuca/f5a14ed9cb76e7ad2f4f6b11361516f5/raw/2c41c8e14f6834a4a3e44f1846e26362ede38da4/Footnotes.md https://gist.githubusercontent.com/richsuca/f5a14ed9cb76e7ad... [1] https://python-markdown.github.io/extensions/footnotes/ https://python-markdown.github.io/extensions/footnotes/ [2] https://gist.github.com/richsuca/f5a14ed9cb76e7ad2f4f6b11361516f5 https://gist.github.com/richsuca/f5a14ed9cb76e7ad2f4f6b11361...
- breck 4y ago
  Thanks for the comparison! Really appreciate it. I think I'll copy some of the style from yours. I really like the smaller font size for the notes, the different font color, and in particular the link back to where the note was used! Double linked list, I love it! Stylistically I like the more minimal look of (the lack of brackets, and I think n may change link color to black): https://ab1908.github.io/2021/08/24/footnotes-in-web-content.html https://ab1908.github.io/2021/08/24/footnotes-in-web-content...
chrstphrknwtn 4y ago
All I get is a blank window in Safari.
- macintux 4y ago
  Works on my iPad. Any JS restrictions in your browser?
  - chrstphrknwtn 4y ago
    Nope, just JS errors [Error] SyntaxError: Unexpected token '='. Expected an opening '(' before a method's parameter list. (anonymous function) (libs.js:16558) [Error] ReferenceError: Can't find variable: AbstractTreeComponent Global Code (app.js:4) [Error] ReferenceError: Cannot access uninitialized variable. (anonymous function) (try.scroll.pub:17)
    - breck 4y ago
      Interesting. Which model # iPad and iOS version?
      - chrstphrknwtn 4y ago
        macOS 13.0.1 (22A400) Safari 16.1 (18614.2.9.1.12)
        macintux 4y ago
        Very odd. I'm running the same versions on my (Intel) laptop, and the JavaScript console is error/warning-free.

59 points by breck 4y ago

At the risk of Dropboxing myself: what is the advantage of this over the existing Markdown syntax for footnotes[1]? It looks very similar, but with a harder to parse grammar. [1]: https://www.markdownguide.org/extended-syntax/ https://www.markdownguide.org/extended-syntax/

SPBS 4y ago
it looks like it aggregates all footnote definitions into one where it can be printed with the keyword 'notes' (hardcoding? too clever? what if you want to separate footnotes?)
- reagle 4y ago
  I can’t see what this offers over pandoc markdown or it’s successor: https://htmlpreview.github.io/?https://github.com/jgm/djot/blob/master/doc/syntax.html#footnote-reference https://htmlpreview.github.io/?https://github.com/jgm/djot/b...
  - pbronez 4y ago
    Shot is new to me, thanks for sharing. Looks like a nice iteration on CommonMark. I’ve preferred Asciidoc for its availability to handle complex nested headers and internal links; djot’s custom attributes and local-first link parsing might handle that well. https://djot.net https://djot.net
tux 4y ago
WOW I didn't even know markdown has footnotes will definantly come in handy for one of my projects. Thank you!
- bmacho 4y ago
  It doesn't have footnotes. Some supersets do.
  - woodruffw 4y ago
    Right, but it's worth noting that those supersets are very common. I'd say it's actually less common to run into a "barebones" Markdown implementation these days than to run into a GFM or close-to-GFM one.
    - deleted 4y ago
      [deleted]
    - deleted 4y ago
      [deleted]
  - teekert 4y ago
    Yes, for example in Hugo [0] I can do this: This is some text with a footnote.[^1] [^1]: And that's the footnote. [0] https://gohugo.io/ https://gohugo.io/
breck 4y ago
> At the risk of Dropboxing myself This made me laugh. I appreciate you. > but with a harder to parse grammar Grammar is actually quite simple once you've mastered the Grammar language (https://pldb.com/languages/grammar.html https://pldb.com/languages/grammar.html) which has almost no documentation and is full of bugs. > what is the advantage of this over the existing Markdown syntax for footnotes[1] I can't speak definitively yet. I think it will be better but I need to use it for a few months to be sure. There are some subtle things I think will be important.
- woodruffw 4y ago
  Thank you for sharing that! In case I came across as overly negative: I think the overall syntax and project here are very cool. I’ll be following your work!

sillysaurusx 4y ago

I like the URL syntax. It's a clean separation between typing a sentence and attaching a link within that sentence. Nicely done.

chrismorgan 4y ago

I’ve been designing a lightweight markup language of my own in recent months, and yesterday I finally settled on a syntax that I like for notes: links (which must always be delimited in my language), but with a leading caret, which will never be present in properly-serialised URLs. (The URL ^x should be encoded %5Ex—the URL parser will accept the caret, but it’s marked as invalid if anyone cares, and the serialiser would turn it into %5E.) This makes perfect sense, because notes semantically really are links from one piece of content to another. My URLs must always be delimited in angle brackets <…>, and links can be either <url> or [contents <url>]. (I haven’t settled on a syntax I like for reference-style links.) This fits in very nicely with caret starting note references. You can have [spanned notes <^…>] and spanless notes<^…>. (I also reckon on the identifier being optional, so that <^> would be valid, just using the next note body.) This syntax is generically useful for sidenotes, footnotes, endnotes and other presentations of notes—in general, I reckon note presentation should be a presentational rather than a content concern. (Aside: what people on the web call “footnotes” are almost always actually endnotes. Endnotes are typically ergonomically poor in both print and screen media. Something along the lines of proper footnotes or inline-expandable notes mostly requires JavaScript, though with effort, restrictions about whether the content can contain blocks, and perhaps careful tip-toeing around HTML parser implementation details (or deliberately using XML syntax if you’re bold enough) and a mild disregard for nominal validity, you can do it even semantically reasonably without JavaScript.) I reckon most notes should be spanned. To demonstrate what I mean, https://chrismorgan.info/blog/rust-ownership-the-hard-way/ https://chrismorgan.info/blog/rust-ownership-the-hard-way/ shows three types of sidenotes: spanned with an inline source marker, unspanned with an inline source marker, and full block asides which are unspanned. To see my vision most clearly you’ll need a large enough viewport; on small viewports, I currently have the notes inline, with the third type aside, and I’m not happy with the in-flow placement of the asides, which is mostly a paragraph or so above the ideal place, but wanted it to all be pure CSS. Then I started wondering, how many potentially viable characters are there like this, that can’t appear at the start of properly-serialised URLs? Could they be purpose for something else? You start with all Unicode scalar values, then remove (a) all URL code points <https://url.spec.whatwg.org/#url-code-points https://url.spec.whatwg.org/#url-code-points>, because they’re valid in URLs; (b) C0 and C1 control codes because non-printables is an extremely terrible idea for normal people; (c) `#`, as it’s used to begin fragments; (d) `%`, as it’s used for percent-encoding bytes. This leaves: "<>[\]^`{|} and space. Most of them would be a bad idea for various reasons, even if they’d work; ^ and | are the only two that seem reasonable to me. So, ^ for notes. Haven’t thought of anything that fits similarly that pipe could certainly be used for. Could possibly use it for reference-style links, but that’d still be clunky (I would like to support […] matching, not needing [… <|refname>)).

iprathik 4y ago

Clicking on the number should ideal take me to footnote but it isn't. Instead its redirecting to a different page taking about scroll

CGamesPlay 4y ago
Yeah, possibly demo broken, but I don't understand how this is supposed to be a new way to do footnotes at all. Looks like a broken Markdown footnote to me.
breck 4y ago
Ah that is a bug with `try.scroll.pub`. That app was sort of hacked together a long time ago and is due for a cleanup. Sorry about that. https://github.com/breck7/tryscroll/issues/3 https://github.com/breck7/tryscroll/issues/3

verdagon 4y ago

Anyone interested in footnotes might like the way we do it on the Vale site, for example: https://verdagon.dev/blog/making-regions-part-1-human-factor https://verdagon.dev/blog/making-regions-part-1-human-factor Some nice things: * The footnotes are off to the side, so it's closer to the text that mentions it and it doesn't interrupt the flow of the main text. * It uses colors, so it's pretty fast to visually jump to the right one. * We keep the numbers too, for colorblind folks (and those using blue-light filters like f.lux) * It works without javascript! Our markdown->html renderer makes this happen by slicing up the page horizontally, one slice per header. Each slice then has a wide left column for the main text, and a narrow right column for the footnotes. Then if the user happens have javascript enabled, it position:absolute's the footnotes and lines them up a little more precisely with where they're mentioned.

AB1908 4y ago
You may want to explore Tufte CSS. My own article about footnotes/sidenotes: https://ab1908.github.io/2021/08/24/footnotes-in-web-content.html https://ab1908.github.io/2021/08/24/footnotes-in-web-content...
- verdagon 4y ago
  Stellar article! Was definitely worth a read. The sidenote styles are particularly ingenious, I remember trying to get float+clear to work for this and never could, but looks like it's doable!
  - AB1908 4y ago
    Glad you liked it! I'm amazed that you liked it cause it was my first semi-serious blog post haha.
- breck 4y ago
  Oh this is beautiful. Thanks for the link.
  - 4y ago

acqbu 4y ago

Breck, you're a good programmer, just like Terry A Davis!

breck 4y ago
How dare you call me only a “good” Programmer. - Sent from TempleOS

ajnin 4y ago

My favorite way is how French website "Le Monde Diplomatique" does it : the footnotes appear at the bottom of the screen in context as you scroll so that only those referred in the currently visible text are displayed. It avoids awkwardly clicking on tiny superscript numbers and annoyingly scrolling back and forth between text and footnotes. For an example : https://www.monde-diplomatique.fr/2021/01/PIGEAUD/62633 https://www.monde-diplomatique.fr/2021/01/PIGEAUD/62633

yinyang_in 4y ago
this is beautiful implementation. Would be nice to see how implementation was done ?
- jer0me 4y ago
  Perhaps using Intersection Observers: https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API https://developer.mozilla.org/en-US/docs/Web/API/Intersectio...
malshe 4y ago
This is fantastic! Dirk Eddelbuettel and Jonathan Gilligan have an R package (https://cran.r-project.org/web/packages/tint/vignettes/tintHtmlIntro.html https://cran.r-project.org/web/packages/tint/vignettes/tintH...) that shows footnotes and many other objects in the sidetones. I like that format as well. But it is static and doesn't't change dynamically like this one in the French website you have linked to.

richsu-ca 4y ago

Something different. I have been using Markdown Footnotes extension [1] and found its syntax to be natural to Markdown. Here's the same sample as OP in Markdown Footnotes syntax. There is a link to the rendered page [2]. https://gist.githubusercontent.com/richsuca/f5a14ed9cb76e7ad2f4f6b11361516f5/raw/2c41c8e14f6834a4a3e44f1846e26362ede38da4/Footnotes.md https://gist.githubusercontent.com/richsuca/f5a14ed9cb76e7ad... [1] https://python-markdown.github.io/extensions/footnotes/ https://python-markdown.github.io/extensions/footnotes/ [2] https://gist.github.com/richsuca/f5a14ed9cb76e7ad2f4f6b11361516f5 https://gist.github.com/richsuca/f5a14ed9cb76e7ad2f4f6b11361...

breck 4y ago
Thanks for the comparison! Really appreciate it. I think I'll copy some of the style from yours. I really like the smaller font size for the notes, the different font color, and in particular the link back to where the note was used! Double linked list, I love it! Stylistically I like the more minimal look of (the lack of brackets, and I think n may change link color to black): https://ab1908.github.io/2021/08/24/footnotes-in-web-content.html https://ab1908.github.io/2021/08/24/footnotes-in-web-content...

chrstphrknwtn 4y ago

All I get is a blank window in Safari.

macintux 4y ago
Works on my iPad. Any JS restrictions in your browser?
- chrstphrknwtn 4y ago
  Nope, just JS errors [Error] SyntaxError: Unexpected token '='. Expected an opening '(' before a method's parameter list. (anonymous function) (libs.js:16558) [Error] ReferenceError: Can't find variable: AbstractTreeComponent Global Code (app.js:4) [Error] ReferenceError: Cannot access uninitialized variable. (anonymous function) (try.scroll.pub:17)
  - breck 4y ago
    Interesting. Which model # iPad and iOS version?
    - chrstphrknwtn 4y ago
      macOS 13.0.1 (22A400) Safari 16.1 (18614.2.9.1.12)
      - macintux 4y ago
        Very odd. I'm running the same versions on my (Intel) laptop, and the JavaScript console is error/warning-free.