Footnote markdown plugin

Oooh, nice! Thanks for the link :slight_smile:

The thing that frustrates me most about Markdown is the inconsistent support for extensions. Sticking to the “lowest common denominator” is too limiting, whereas having to remember what works where is a PITA.

I skimmed this document. Looks like tables work both here and in github, so do fenced code blocks (well, that one’s no surprise). Heading IDs work in neither. Nor do definition lists. Strikethrough works in both. As do task lists, emoji and automatic URL linking.

Supporting footnotes here would keep the supported syntax consistent with github, FWIW. So that’s a +1 from me just for that reason.

2 Likes

I hit this discrepency in Supporting sdists and source trees in PEP 665 - #63 by pradyunsg yesterday.

Exploring this further: PSF is on a hosted-by-Discourse setup/plan, wherein the hosting and plugins on the instance are provided by Discourse. The footnotes plugin is only available in their highest tier of “Enterprise plugins”. (>.<)

And… footnotes[1] are here! :slight_smile:


  1. Yay! ↩︎

1 Like

Posting an example of a footnote [1] for illustration. As with other hyperlinks, the color is a bit dark in the Dark theme–at least in the editor’s Preview Pane. :thinking:

NOTE: The footnote is created with the Markdown code ^[This is a handy footnote...] and looks like a proper footnote while editing until you submit the footnoted post. Then it turns into an inline note as in @pradyunsg’s post. This is strange behavior. Does anyone know why Discourse does this?

NOT SOLVED. Still getting nothing but inline notes. A post over at meta.discourse.org shows two locations for the caret:

  • Before the square bracket with text inside: ^[A pithy inline note]
  • Inside the first square bracket to make a ‘goto’ or ‘jump’ type label/reference [^1]

Examples:
The caret in front of the brackets produces an inline note [2].

The caret inside with a label produces a standard footnote [3]. The label itself (at the footnote itself) is identical except has a colon after it, like so [^1]:


  1. This is a handy footnote with links back and forth from the body while editing but turns into […] after submitting. Wuzzupwidat? ↩︎

  2. …like this ↩︎

  3. Begone with your pithy note. Here is an amusing limerick! ↩︎

I always get inline (popup) footnotes. I don’t like them, and I wish I could get “standard” footnotes, but I assumed I was stuck with what Discourse gave me. There’s no “display footnotes inline” setting in the user preferences :slightly_frowning_face:

I don’t like them, either.

I think I’m going to use folding dropdowns until we have proper footnotes <1>.

<1>

Because I can put them immediately after the paragraph that relates to the extra info–and they might, when collapsed, even take up fewer lines than a long footnote would. (Tried to use square brackets around the ‘1’ but couldn’t figure out how to escape the square brackets to keep them from confusing the markdown interpreter.)

Perhaps the word “inline” means you inline the text of the footnote when you write it; that is, it has nothing to do with the rendered output, it has to do with how you write the markdown.

From Discourse Footnote - plugin - Discourse Meta, it seems to be a site setting:

Additionally you can either enable or disable “inline” expansion with display_footnotes_inline

I’m amongst the number who would prefer “normal” footnotes[1], but as it is a site-wide setting it would be up to the @admins to change it, and I’m not even sure they can – Pradyun mentioned we’re on a hosted plan, so we might not have access to every setting.

A


  1. i.e. without inline expansion ↩︎

1 Like

We’re supposed to have the option of either inline or footnote. That’s why there are two positions for the caret.

Discourse’s meta.discourse.org site is having the same problem. Evidently it’s supposed to work as advertised but got broken somewhere along the line. It was reported on 31 March and was acknowledged as WIP on 1 April by one of the Discourse founders.

@mlgtechuser – Erlend is correct here. The two ways of writing the note ([^1] & [^1]: spam spam ham eggs vs ^[spam spam ham eggs]) are divorced from the rendering of the footnotes into HTML – that is what is controlled by the site setting.

I believe the bug report you linked is about referencing the same footnote twice rather than the HTML display – a PR to fix that was merged in early April.

A

That excludes the notes from emails, contrary to the other forms.

1 Like

I believe you’re correct, Adam. The topic name over there could use some clarification.

The GIF shows the mark-down pasted in from the footnote announcement with the [^sartre] + [^sartre]: labels rendering in the topic as inline “tooltip”, but the second reference doesn’t trigger any popup text.

Yes, the Footnote Announcement Post makes a distinction between “single line and multi paragraph footnotes”.

Additionally you can either enable or disable “inline” expansion with display_footnotes_inline

@admins, perhaps this switch immediately above can be turned off to restore standard footnote rendering at message bottom…?

From an Admin over at meta.discourse.org:

If you type ‘footnote’ into your settings search bar it should pop up? The other good way to find the settings for an individual plugin is by going to the plugin page and clicking on the :gear: settings next to the specific one (which filters the settings with one of these: plugin:discourse-footnote )

2 Likes

Not that I doubt you all, but I’d be curious to hear the specifics about the disadvantages of the inline footnotes relative to displaying them all the way at the bottom of the post. It seemed like a lot of people mentioned they didn’t like them, but it wasn’t really clear to me their specific reasons.

Personally, I prefer having the note local to where it references, as opposed to having to disrupt my reading flow and jump all the way to the bottom of a long message and back to read the note, and it would discourage me from using them myself to add ancillary details.

However, there are a few practical issues with it. Besides the preview rendering inconsistency, the UX for copying them is very finicky (you have to hold down on the text, and then before letting go press Ctrl-C, since it will vanish once you release your mouse), and quoting them does not work correctly (see below), though hopefully those bugs could be fixed.

Test quote (to illustrate the bug quoting footnotes):

They are not visible without clicking on them (yes, I know that in a long post you have to scroll down, but not all posts are that long, and even if they are, you can scroll with the keyboard).

You can’t (easily) copy and paste from an inline footnote. You can’t quote an inline footnote. You say “those bugs could be fixed”, but the lack of an option to choose the rendering format could just as easily be fixed, surely?

Your “test quote” quotes some normal text with its footnote (and, by the way, it doesn’t render correctly for me). I’m talking about just quoting part of a footnote[1] - and yes, I have wanted to do that in the past.

Having said this, I’m not trying to claim that inline footnotes are objectively bad, just that people have different preferences, and those preferences are apparently strong enough that having an option, so the user can choose for themselves, seems like a sensible approach.


  1. For example, “just these four words” from this footnote. ↩︎

3 Likes
A few caveats... (Click to unfold)

Hopefully this is a discussion and not a debate. I’m happy to share my reasons and consider the viewpoints of others, but this topic is too minor for anything like an argument. Any individual point someone might offer can be disparaged, derided, dismissed, or any other various “d” words that don’t actually contribute to a measured, considerate exchange of ideas (a collegial discourse). ANy Indeed, any of the points below may seem minor–and may actually be minor. Taken as a whole, though, minor but frequent departures from a pleasurable experience taint the overall experience. With this topic in particular, the user experience is largely subjective and stylistic, so respondents should be very conscientious of refutations that border on or are explicitly ad hominem attacks. Also, it is far too easy to overlook the pleasure experienced by someone highly sensible of and attuned to artfully presented, well-composed text–especially prose.

That said, here are my thoughts and reasons. This is not at all exhaustive. I’m running late for a dinner appointment but these are the ones that come immediately to mind.


The inline popup note has its place, for sure, as do the spoiler blur and Hide Details fold. (I wish Hide Details didn’t enforce padding above and below, but that’s another topic.) As with any tool, the inline note’s value, strength, and advantage is in the skillful and appropriate use of it. I’d say that the main shortcomings are due to the current implementation (happily, software is highly mutable).

  1. PRO: convenient; click it to show.
    CON: you can’t simply click again to hide. A mouse move before click is needed (happily, software is highly mutable).
    FOOTNOTE: The footnote as rendered in the message/post editor preview pane has hyperlinks that look like could be used to jump quickly and conveniently to the note and back up to the body. The note itself even uses a “return” character for the hyperlink.

  2. PRO: convenient; read the note in situ and move on.
    CON: visually obstructive in its current implementation.
    The ellipsis button graphic contrasts significantly with the surrounding text and is not aesthetic (happily, software is highly mutable–you see the theme). The ellipsis could be much smaller and still serve its purpose.
    FOOTNOTE: The footnote superscript is subtle, especially with the low-contrast hyperlink text in the Dark Theme.

  3. PRO: good for short supplemental notes.
    CON: long passages overlay the text and disturb the reader’s orientation within the paragraph. It can be jarring, visually.
    FOOTNOTE: Because footnotes are effectively an appendix, they can be long without disturbing the reader’s “flow” through the body.
    FOOTNOTE: The footnote presented on a clean/clear background with margins all around is a smoother (less noisy) presentation than the popup note overlaid on the message/post body text.

The thought-provoking factor here is that the carat has two defined locations but produce the same result (an inline note). It seems that the Discourse product managers (or the plug-in designer) had a second method in mind–presumably a standard footnote–but somehow it hasn’t yet been realized.

Examples:
The caret in front of the brackets ^[note] produces an inline note [1].
The caret inside with a label [^label] also produces an inline note [2].


  1. Carets are yummy! ↩︎

  2. What’s up, Doc? ↩︎

2 Likes

This one in particular matters to me, as I have a tendency to use footnotes to add “supplemental” material (which is often rather long). Maybe having intra-document hyperlinks[1] would be a more appropriate solution for that, but at that point it starts feeling more like writing a formal document than a message…

Edit: Yeah, nested footnotes are utterly broken with the “inline 3 dots” layout. It renders just fine in the preview pane, in “out of line” form. For reference, this is what I wrote as input:

Maybe having intra-document hyperlinks[^1] would be a more appropriate solution for that, but at that point it starts feeling more like writing a formal document than a message...

[^1]: Does markdown even *have* intra-document hyperlinks (to arbitrary paragraphs)? I've never looked, because in general I find that "advanced" stuff in markdown is inconsistently supported on different platforms[^2].

[^2]: And yes, I'm indulging my tendency to over-use footnotes[^3], to make a point about usability. This is easy to write. Is it easy to read in the "inline" form? Let's find out...

[^3]: If Terry Pratchett can do it, who am I to say it's a bad idea? :slightly_smiling_face:

  1. Does markdown even have intra-document hyperlinks (to arbitrary paragraphs)? I’ve never looked, because in general I find that “advanced” stuff in markdown is inconsistently supported on different platforms[2]. ↩︎

  2. And yes, I’m indulging my tendency to over-use footnotes[3], to make a point about usability. This is easy to write. Is it easy to read in the “inline” form? Let’s find out… ↩︎

  3. If Terry Pratchett can do it, who am I to say it’s a bad idea? :slightly_smiling_face: ↩︎

2 Likes

Quoting from your footnote – The commonmark spec doesn’t define footnotes having just checked, so every implementation will be a vendor extension, and hence there will be inconsistencies.

There’s also no option to choose what markup language [1] you write in, but I imagine Discourse would balk at supporting that particular option!

A


  1. vanilla commonmark / GFM / reStructuredText / asciidoc / BBCode ↩︎

Yeah, I know. But can’t I dislike the way Discourse has implemented it? That’s all I’ve ever said here, that I dislike the current implementation and would appreciate an option to have the final render look the same as the preview.

I’m going to drop out of this discussion now, as I seem to be getting criticised for things I never said[1]


  1. Not specifically this response, but a few recent comments :slightly_frowning_face: ↩︎

2 Likes