Add Footnotes Support

[androb]

Implement a block for footnotes.

---

Prior pull requests: #2818

[swissspidy]

Interesting suggestion, thanks! Have you had anything in mind how this could be resolved UI-wise?

I mean, displaying footnotes is one thing. But you also need to add them to words/sentences/paragraphs somehow in the first place.

[androb]

It is a good question. It is an "insert inline at cursor" action which I do not believe we have modeled before.

Under the current UX regime, I believe it would belong alongside link on the inline toolbar that pops up over each block... but it doesn't feel like a commonly enough used function to occupy such prime real estate.

May be we keep it in the Insert drop-down but it behaves somewhat differently?

Perhaps @annaephox has some thoughts?

[karmatosed]

I really like this idea and think a lot of users would want this. I do wonder if it's a block or a plugin that goes with Gutenberg though. Worth exploring either way.

[BoardJames]

The tricky bit with footnotes is that they need to be coordinated across block boundaries. In my mind footnotes need 3 things:

• Link to some external resource
• Short description about the external resource (could be pulled from the external resource directly using the same techniques as for embeds)
• Knowledge of their position in the overall document so they can be numbered.

If the editor has control over the whole document then they are easy. Just allow users to insert a link with a "footnote" toggle button that applies a style or a data attribute. Then before save of the entire document, you process the document to find all of the link tags that have the appropriate style or data attribute. You move the links to the footnote block of the document and then replace them in the edited block with a link to the entry in the footnote. On edit you do the reverse, you find all the footnote locations and reinsert the original link.

[ellatrix]

I'm pretty excited about footnotes. I think it should be supported in core, as it's something that really needs to be baked in and it's quite common for people to use.

Adding

• We probably don't want to be adding too much UI when you're not using them. We'll need a button in the formatting toolbar for sure, but maybe we can introduce a "Footnotes" block, which is inserted at the bottom, and only with this block present the button in the formatting toolbar pops up.
• There should be a shortcut. Probably [1] etc. (order should be autocorrected) and using an existing number links to an existing footnote. [#] (or any not yet existing number) to create a new item without having to know the correct number.
• It would be nice if, once you click the button or complete the shortcut, a field slides in at the button that auto-focusses (you can continue typing from the shortcut), enter submits it and puts the caret back after the reference mark.

Editing

• The reference mark [1] looks like a superscripted link, and when the caret goes in the boundaries, the footnote field slides in again at the bottom.
• You can also go to the bottom and edit the footnotes in the footnote block. The reference mark links to the footnote, and the footnote links to the reference mark.

Deleting

• I think for sanity, it should only be possible to delete the reference marks (which deletes the footnote). Of course you should be able to bring it back with undo.

At a state/reducer level, insertion and delete (or only post save if we don't want numbers/order in edit mode) will both have to look through all editable content to determine order.

[ellatrix]

Actually, we don't even have to loop through all editable areas, only look at the editable area the current one is in and sort. We could add the footnotes as properties to each block, and the footnotes block could put these together based on the block order.

[ellatrix]

Going to assign to look at in the near future.

[aaronjorbin]

I love footnotes, but I think this might be something that belongs as a property to the post, rather than as a block. Two thoughts:

1. How do we ensure if it is a block, that it can be locked to the bottom of the post (i.e. that there is never a case when footnotes are in the middle of a post)
2. If you are using multiple pages ( via <!-- next-page --> or whatever form that has taken in Gutenberg) in a post, that the footnotes appear on each page and are numbered correctly for that page.

[dsifford]

@iseulde I'd be happy to work with you on this.

Check out https://wordpress.org/plugins/academic-bloggers-toolkit/. I've been working on a pretty good academic citations plugin over the last 3 years (although, I am biased!).

There's quite a few hidden difficulties that come with managing references and footnotes that I'd imagine most people don't consider early on (I was one of those people). I'd be happy to discuss this in detail if this is something you'd be interested in pursuing.

Related: https://github.com/dsifford/academic-bloggers-toolkit

Pushing a rather large codebase update to wordpress.org in the next week or two which has quite a bit of refactors necessary for gutenberg.

[karmatosed]

This is just a v1 but the basic design could look like this:

1. A simple option is added to the toolbar. We will have to iterate the graphic but after doing some research this is a good starting iconography for footnotes.

2. Following on from creating a footnote, the footnote block would appear. This has no options, we can discuss if it should have options. I'm cautious this can be deleted even, if you have footnotes why would you delete? Isn't just remove a footnote the delete?

Perhaps people would want a title, but for now this shows the minimum I think footnotes would make sense. I'm very cautious we do not spiral this feature, it could easily spiral.

[jasmussen]

Love those mockups, Tammie, I think they provide a solid basis and can help our minds grok the side effects and everything. The "deleting" thing is one issue that immediately pops up, but that seems solvable by looking at how other editors have done it — perhaps a "are you sure" prompt is sufficient.

The icon also is almost there, with a popout label I'm sure people will get it.

But one thing I keep coming back to is — it's very very clear that we need to be able to both add more buttons to the quick toolbar, and stay responsive.

This is how Google Docs does it:

This is how it could look for us:

[dsifford]

I've still neglected to update the docs for the new update, but the old ones should be close enough to get you on the right track.

Does it have any performance impact? Is everything generated cacheable?

This is one of, if not the, most important consideration I had when updating the plugin. Everything that I could possibly cache, I did. Also, the expensive functionality (notably, re-parsing out editor citations and footnotes for changes) only occurs after a user is done typing. You can see this by adding in a footnote/citation and simply using the backspace key to delete it out.. After you stop typing for a few seconds, or click somewhere else, the footnotes list/bibliography will update.

There's still a few perf things that need to be added, but nothing too huge.

[nicopujol]

Here is a test post containing a legacy footnote (MS WORD import, I believe) with a hyperlinked [1], and a footnote using your new plugin, showing as an asterix. https://bit.ly/2LRUZqI. Is there a way to make footnotes the same as the legacy example, i.e. its standard text size and with a hyperlink? Mobile users may find references easier to access and read that way.

[dsifford]

@nicopujol Sorry for the delay. It is possible to make it work in the way you describe, absolutely. There are some potential issues though that I should point out:

The most salient issue is the strict differentiation of footnotes from in-text citations. Some (of the now well over 4000 available citation styles there are to choose from) are styled precisely in the way you have listed (e.g. [1], [2], [1,4,5-9], etc..). So that's the reason I opted to go straight to using symbols.

The other issue with using the traditional anchor-style footnotes is with posts that are paged. Anchors just simply will not work in those instances.

After checking out your example page though, it is clear that the tap targets need to be made bigger on mobile; especially so when footnotes are positioned right next to a link. That's something I will probably work on.

Another thing (as I mentioned in my demo video): I do think there is some merit in allowing users to choose between symbols, numbers, and letters for their footnote format. That's something I'll likely look into after releasing the update. I think it should always default to the symbols though, just for safety with in-text citations.

To comment on your question Re: automatically converting legacy footnotes to this format: I don't think that's worth the effort. Too many potential variations to account for and the return frankly isn't really worth it for the amount of work it would require.

Hope that answers your questions. Good thoughts nevertheless. Again, I definitely think there is some progress to be made on tap targets. 👍

Edit: Also, I'm wondering why it is that you are even using footnotes in the first place? Both of your examples cite sources. Wouldn't it be better to use citations for that?

[nicopujol]

Thanks @dsifford.

To comment on your question Re: automatically converting legacy footnotes to this format: I don't think that's worth the effort. Too many potential variations to account for and the return frankly isn't really worth it for the amount of work it would require.

Agree, no need to convert legacy citations and footnotes. Only thing is the numbering overlaps, when using a citation.

Hope that answers your questions. Good thoughts nevertheless. Again, I definitely think there is some progress to be made on tap targets. 👍

Great to hear the test was helpful.

Edit: Also, I'm wondering why it is that you are even using footnotes in the first place? Both of your examples cite sources. Wouldn't it be better to use citations for that?

Footnote was the first popup which came on the editor. I see now that citations are located on the editor's sidebar. I replaced the example above on the same post with a citation (web page type, since book did not allow including a URL).

[dsifford]

Yeah, unfortunately in those situations, you'd just need to replace your old citations with new ones using the plugin in order for them to be tracked.

Looking back at your test post I now also see that adding transition: all to link elements within the tooltips causes them to behave weirdly when the tooltip hides due to the transition still applying. I'll have to stub those out in the plugin as well.

[dsifford]

@nicopujol Did you try using the ISBN to insert your book citation? Assuming the book is indexed in google books, that is another alternative. If not, yeah, you'd have to add manually. I'll look into maybe adding a URL field to books.

[jcklpe]

@dsifford

Hey sorry for the delay in testing the plugin.

Unfortunately when I tried to activate the plugin I got this response:

Parse error: syntax error, unexpected '}', expecting identifier (T_STRING) in /home/jcklpe/jackalope.tech/wp-content/plugins/academic-bloggers-toolkit/php/admin.php on line 16

Some additional thoughts:

I know this is primarily an academic tool, but my biggest interest is in the footnotes functionality, and I'd love to see that expanded a bit more. Namely, I think it would be interesting to allow a wider diversity of content to be linked through footnotes. So right now it can only be used to display some text, but it could also be used hypothetically to show a video or image on mouseover. It seems to me that if one were to treat the individual footnotes as their own individual sub blocks you could possibly genericize the footnote content to the point where it could easily be adapted to almost any other kind of gutenberg child block type, even ones not created by you specifically. Just a thought.

[dsifford]

Whoops, sorry @jcklpe... I forgot to mention that I'm being super opinionated and am requiring PHP 7.2+ for the update since I work on this in my spare time and don't feel like supporting older PHP versions.

but it could also be used hypothetically to show a video or image on mouseover. It seems to me that if one were to treat the individual footnotes as their own individual sub blocks.

Interesting idea! Unfortunately, that's a bit outside the scope of the plugin I'm working on so I'll let others take the lead on pursuing something like that.

[jcklpe]

Totally, yeah I prefer to use php also. This is on my host, so I'll have to see if I can upgrade stuff.

[paaljoachim]

Hey Ella @ellatrix

It would be great with a status update to how the issue is coming along.
Thank you!

[rodrigo-arias]

Thanks for everyone's work here, it will be great to have this feature.

[FedericoPistono]

Thanks for the great work! 🙏🏻

Will definitely use footnotes in Gutenberg on a daily basis as soon as they're available.

[nooblag]

I'm excited for this to come out too. :)

[mtias]

Marking this as done!

[bph]

PR to introduce Footnotes to WordPress block editor:

• Footnotes: try with post meta #51201