Footnotes now supported in GitHub Markdown | Hacker News Reader

Footnotes now supported in GitHub Markdown

github.blog

261 pointsgampleman75 comments

It's funny to watch Markdown gradually reinvent HTML as it originally was (though with much more readable syntax)

And I don't actually think that's a bad thing, so long as it stops there. HTML has become much more than documents, so having a constrained subset dedicated to documents is helpful.

Markdown hasn't changed a bit from its reference implementation, it can't.

Everybody who grabbed onto Markdown and is forking it because they're realizing that it was a very simple tool to solve one man's blogging problem and ignored all the other more comprehensive LWMLs is reinventing HTML.

GitHub-flavored Markdown is different; it's almost taken over as the de-facto standard. There are lots of wacky extensions out there, but this isn't just another one of those.

What's interesting about that is that John Gruber uses footnotes extensively in his own blog posts (and has since approximately 2005), but chooses to implement them with HTML snippets rather than having created a dedicated Markdown syntax for them.

For example, see https://daringfireball.net/2005/07/footnotes.text

To be fair, it is simpler than HTML. Like Java vs. Python. You can sure do a lot with Java, but sometimes you just want the beauty of Python without injection, ya know?

I don't understand how you can say that. Markdown is massively more complicated than the equivalent HTML. HTML syntax is simple: Every gizmo is expressed as a <tag> and optionally an end </tag>, there are escapes for <, > and &, and that's all that ever needs escaping.

Markdown, on the other hand, has a syntax that is ever expanding. It's all exceptions to exceptions to exceptions (exceptions all the way down).

For example, what happens if in a markdown document talking about regular expressions you have this text: [^A-Za-z]. Will it be interpreted as a footnote? Or is it an exception? Who knows, only trial and error will tell.

And it may be handled differently between the many "flavors" of markdown!

In my experience, with decent editor assistance to help with boilerplate, closing html tags, etx. I enjoy writing simple docs more in html

You're talking about parsing/syntax, but what matters here is semantics. (Normal) Markdown maps to a small subset of all possible HTML tags, most of them on the simpler end of things, and that makes its overall scope and semantics simpler than those of HTML, even if its syntax is not.

Means and ends. If your means are complex, but the ends you are achieving are simple, then you're not getting good value for money. If I am to abide complex syntax then I'd better get sophisticated, powerful semantics in return.

HTML 1.0 (no CSS, no JS, no floats) is very similar in scope to Markdown. I wish every site that uses Markdown would allow me to write something like HTML 1.0 instead. It would be so much easier, at least for me.

The whole point of machines is to do tedious or hard work so people don't have to.

I don't think it's really about parsing/syntax. Or, rather, it is, but that has implications not just for the person writing a markdown parser or renderer, but for the person writing documents in markdown as well.

With HTML, I know that anything inside angle brackets won't get shown, because that's a directive to the rendering engine to do something. Put another way, only <, >, and I guess & are special and need to be escaped if I want to use them. Everything else will show up as I've typed it.

With markdown, a future feature addition could actually change the layout or structure of an existing document, because arbitrary characters (and sequences of characters) mean particular things. Previously, [^1] was a hyperlink to somewhere else (assuming I put "[^1]: https://wherever.com" somewhere else on the page). Now it's a link to that "[^1]: https://whatever.com" text on the same page. This change may have broken existing documents.

Keep in mind that it’s not all about simplicity. One of the selling points of MarkDown is that it’s legible even when left in its plain text source format.

HTML is ugly when left in its source format.

I'd wager that GitHub is one of the biggest publishers of larger-than-bite-sized Markdown documents, and this "selling point" (an argument which I both agree with about [original] Markdown and agree that this is a good property) is pretty much untrue for any given piece you'll find on GitHub. This is thanks to several factors including "GitHub-Flavored Markdown" differing so wildly from the original flavor, and the typical GitHub user just not giving a shit about how the raw form looks—treating it as just another non-WYSIWYG formatting language in the vein of HTML or TeX, since all they're really after most of the time is for their README to work as a substitute for a product landing page.

Pug is HTML but beautiful and more powerful, I’m surprised it hasn’t been brought up.

The best format I’ve found to author web pages, though, is definitely MDSvex [1], which is essentially markdown with built in syntax highlighting for code blocks, vanilla HTML if needed, and Svelte / Svelte components for any reactivity / reusable components if JS is needed. Stick some pug in the Svelte Component and I’ve got unlimited power in a beautiful, readable syntax with 0 boilerplate, all compiling to vanilla HTML and optionally hydrating JS. Love it!

[1] https://mdsvex.com

Just use restructured text (rST) already.

No, asciidoctor! Asciidoctor is the most intuitive markup format there is (except maybe Pollen, but that’s a non starter for most people).

Also, rST can’t even do bold italics.

Nothing beats org-mode.

Yeah, Org mode has supported footnotes since 2008:

https://github.com/bzg/org-mode/commit/40a149354c4e5992abac4...

If only I could have it in any other way than emacs...

Makes me wonder, since there is evil mode and opinionated Emacs disributions like Spacemacs und Doom Emacs, whether there is a potential for an org-mode focussed and optimized Emacs distribution.

Ease of use should be one of the core goals, then.

I would love that but then again org-noter and pdftools compliment base org-mode nicely.

Yeah, the lack of nested formatting in rST is crazy. For me it's annoying I can't just do a simple monospace formatted link in pure rST. Sphinx helps a bit with that depending on what you want to link, but it's not really controllable at the rST level like it is in other markup.

Yes... I do like asciidoc. Think it was lack of easy toolchain in python ecosystem that made me move away from it.

Maybe asciidoc3 har improved the situation.

Never needed bold italics. :)

I'm personally very conservative about what I want added to markdown. I use it heavily because it doesn't provide me too many options.

That said, links and references are a nice thing to have done well.

I use Joplin to take notes, it's Markdown-based and it also includes some interesting extras like Mermaid support for diagrams.

http://joplinapp.org/

https://mermaid-js.github.io/

HTML doesn't have footnotes, does it?

It basically does. You can use anchors to approximate the behavior described here (it will be more verbose, but that's to be expected)

HTML 5 has the aside tag, which has the semantics of footnotes.

"Aside" is very rarely used as a footnote, and doesn't inherently have footnote semantics.

Not even in W3C's rather underrepresented suggested usage (as distinguished from common practice):

The objective of this technique is to use the HTML5 aside element to indicate that it's content is tangentially related to the main article or a parent section. The aside element represents a section of a page that consists of content that could be considered separate from that content. Such sections are often represented as sidebars in printed typography.

https://www.w3.org/WAI/GL/wiki/Using_the_aside_element_to_in...

https://awkawk.github.io/using_aside_content.html

Dive Into HTML5 anaogises <aside> to sidebars:

The aside element represents a section of a page that consists of content that is tangentially related to the content around the aside element, and which could be considered separate from that content. Such sections are often represented as sidebars in printed typography. The element can be used for typographical effects like pull quotes or sidebars, for advertising, for groups of nav elements, and for other content that is considered separate from the main content of the page.

http://diveintohtml5.info/semantics.html

> Dive Into HTML5 anaogises <aside> to sidebars:

However, ctrl+f footnote doesn't return anything. What's the current best practice for writing footnotes with semantic html? If I were to implement footnotes with <aside>, how would it look like?

> What's the current best practice for writing footnotes with semantic html? If I were to implement footnotes with <aside>, how would it look like?

https://html.spec.whatwg.org/multipage/semantics-other.html#...

Well, that's just all kinds of wrong.

That's the thing: there really isn't one.

It frankly boggles my mind that a markup language created by and for academics has neither footnotes nor formulae as first-class features.

To the extent that Markdown does implement a specific footnote syntax, it's actually ahead of HTML in that regard.

I think people are referring to the practice of effectively creating footnotes with HTML anchor tags [1]

[1] http://karlwinegardner.blogspot.com/2011/02/how-to-create-fo...

Not sure how useful are footnotes but the lack of ability to assign stable ID to headers is annoying.

Something like:

    ###|about What is all this about?

And #2 in wish list is built-in support for `<details>` - collapsible sections - quite useful in documentation.

The details html tag works fine on GitHub; or did you mean you’d like a new syntax that’s more markdownesque?

EDIT: Definite +1 for the stable headers id suggestion. I implemented something similar in a proof of concept app a while back, but it was a suffix rather than a prefix, in brackets, like so:

    # About this project { #about }

It worked really well, and the syntax allowed for additional properties like css like class syntax. Thouh we referred to them as tags because they were used to tag sections, paragraphs etc., so we could do some interesting aggregation later on.

I would rather define some MD rule for <DL><DT><DD> and ask viewers to use collapsing

    ### Properties

       + #### innerHTML

         Get/set inner HTML content

       + #### innerText

         Get/set content as text

    ### Methods

We did something similar to this, but used ~ instead, like so:

  ~ Definition title
    The definition data should be indented at the same level
    as the title. This let's you nest definitions also:

    ~ Like this
      Here's a nested definition.

We also allowed : instead of ~ but most people seemed to prefer the latter. We didn't collapse anything in rendering though, but it's not a bad idea. The resulting markup when rendered to HTML was actual definition lists (<dl>) though, not details, so that'd either have to be done by nesting details or css magic I suppose.

Not sure if this helps you, and you may already be aware of it, but in my gitHub pages markdown I have titles like these:

## <a name="boiler-plate"></a>Removing more boiler plate

I just read that using "id" is the preferred way (see the other reply) "name" is deprecated for this use, but it still works of course (I'm not a web developer, been using the same markdown trick for years)

You can already do this with HTML, if you want to:

### <a id="about"></a>What is all this about?

In your case id is assigned to wrong element.

So to use

    <h3 id=about>What is all this about?</h3>

But what's the point of using MD then?

It’s the “wrong element” but if the goal is to scroll to a given vertical position then it works.

You could choose AsciiDoc instead which lets you choose your own IDs and is supported on GitHub and GitLab

Is https://github.github.com/gfm/ maintained? If so I would have expected to see this addition in there. On that subject, it's been a while since I needed a new markdown parser but I kinda like this feature, where do I find the source for the parser?

EDIT: OJFord answers my question below.

P.S. Why am I forced to watch (and re-watch) an animated GIF when you could have simply shown the source and resulting rendered HTML in my browser?! Meanwhile, the example code they do provide is left completely without a rendered output. Must everything spoon feed video these days? Madness!

P.S.S why is "simple" colored cyan?

Wow...apparently 6 years late[1] to the party?

[1] https://gitlab.com/gitlab-org/gitlab-foss/-/blob/master/chan...

When is Gitlab going to join the performance party?

Pandoc markdown had footnotes in 2008 when I was blogging with it.

Is this implemented in cmark-gfm?

https://github.com/github/cmark-gfm

Yes, simply look at the latest release which contains three bugfixes related to footnotes:

https://github.com/github/cmark-gfm/releases/tag/0.29.0.gfm....

Actually it was implemented in Nov 2017, but only deployed/enabled for GitHub Pages.

https://github.com/github/cmark-gfm/pull/64

See this comment: https://github.com/github/cmark-gfm/pull/64#issuecomment-401...

Which should be dependant on your static site generator. I feel like GitLab stays 2 years ahead of GitLab.

Instead of reinventing the wheel and shoehorning basic functionality into markdown, why not just use a markup format that already “just works”, like asciidoctor?

I think GitHub support Asciidoc already, you just have to specify it.

Or is that GitLab?

GitHub supports it, so I don’t see why they don’t just encourage users to use it instead of reinventing the wheel with markdown

I thought it only rendered files in the repo (match by extension). Does GH also allow asciidoc(tor) syntax in comments and issues?

* Note: Sadly, include is not supported on GH. https://github.com/github/markup/issues/1095

> Does GH also allow asciidoc(tor) syntax in comments and issues?

No, only markdown is “native” to the platform.

Asciidoc looks too much like code.

Awesome. GitHub-flavoured markdown is definitely my favourite Markdown editing experience overall. That’s largely due it being 95% markdown and ‘not Markdown plus a bunch of other cool features with poor interoperability’ that you find in Notion and Confluence.

Is there a proper document editor (eg. Has live preview) that is the same as GitHub-flavored Markdown such that I can copy text into Confluence or Notion and have things ‘just work’? I would use that as my editor and just copy into other places for publish.

Is this a GitHub-specific feature or is it something defined in the MarkDown spec?

It's not part of the original spec for Markdown, but it looks like it's a relatively standard addition to Markdown:

https://www.markdownguide.org/extended-syntax/#footnotes

But do note it's not part of CommonMark yet: https://spec.commonmark.org/current/

I hope it gets there. I like this feature. :-)

Make your desire known on the CommonMark forum topic on this: https://talk.commonmark.org/t/footnotes-now-supported-by-git...

I think CommonMark misses the mark (pardon the pun) by not having tables as part of the spec. Mind you, GFM tables leave much to be desired, but I'm constantly writing tables in my notes and it's frustrating to not see this supported in CommonMark.

They seem to have fixed the code fence dangle render bug at the same time. That's been a sticky one for the better part of a year.

what is this for the uninitiated?

there was a ``` dangle in the last code fence in a post. It didn't always appear, looked to be dependent upon content in the fences, but often enough as to notice.

Does anyone know of a good reference table showing what IS supported on GH vs. something like Goldmark (Hugo's default)?

I find that I constrain myself to the bare minimum in .md because I'm not sure what is supported.

A Markdown Rosetta Stone would be a useful tool.

This might be what you want: https://babelmark.github.io/

A nice addition - I wonder though why GitHub Markdown still doesn't support image resizing. Seems to be one of the most obvious feature if you embed images.

that's pure presentation.

At last. I have used footnotes in Markdown (via the Python library) for many years now, and kept trying to do so in GitHub…

Any new feature in markdown is a bad feature by definition.

You know what's not supoprted in GitHub Markdown? Anchors. There are no functional anchors on any GitHub page. They have something in their markdown that looks very much like anchors but instead of being an actual HTML anchor it requires loading and executing javascript first.

If github wants to actually support real markdown then footnotes are good, but maybe work on supporting anchors first. They're very important for readmes.

Reply on news.ycombinator.com