RichText: Add (foot)notes

[ellatrix]

Description

Fixes #1890.
Blocked by #16428.

Front end:

Notes are not a trivial thing to implement, but they are commonly used, even customary in a lot of fields. I think it’s important that core adds support for them. Adding support for footnotes will also the door for adding comments. They are basically the same thing, just styled differently and only displayed in the editor.

Positioning

There are three possible ways to position footnotes:

• Endnotes: list at the end of a page.
• In the page margin (possible to do in JS).
• In a popover on hover/click (possible to do in JS and perhaps CSS as well).

“Footnotes” don’t really make sense in the context of a web page, so let's call them "notes".

The first is probably the most common way in print, but the latter seems to become more popular on the web.

It’s worth noting that even though the author may not want to display the notes at the end of the page, the markup should still be there so it can be printed and indexed correctly.

Markup

There is no standard way to create notes in HTML. Ideally they should have as little markup as possible, so it’s clear, compact and sensible when editing the HTML directly.

There are two parts:

• The note anchor.
• The note list.

The note anchor should obviously be an a element and link to the relevant list item. But what should be linked? What should the text be? Any other markup?

A very common thing to do is to “hardcode” the numbering, but that seems too hard to maintain, both manually and programatically. In addition it may depend on the language, script, and convention. The numbering should be added in CSS. Numbering is just a stylistic choice when using endnotes.

Another common thing is to use sup, which seems to just be used for convenience. Again, notes might be styled differently depending on your taste, field of work, or language. We should not force a certain style. The markup should be flexible enough to work in a variety of cases.

Notes were originally implemented for print. They where not explicitly linked. Linking is a thing of the web, and we should take it to our advantage as much as possible. E.g. the numbering matters less because of the bidirectional linking. We can also explicitly link the exact text the author wants to reference comment on. If you want to style it differently, fine. You could choose to add a number with CSS :after, in any style you like.

This whole idea to only link text starts crumbling down for two reasons though:

• It’s not possible to link anything inside the text you’re commenting on.
• It’s not possible to have multiple references.

So I made it so that you can both link selections of text or insert a reference mark if there is no selection. I do like linked text much more as it’s more explicit than a reference mark, but as said before, it has limitations.

Finally, an ol element for the note list makes sense to me to automate the numbering. Inside every list item, a back link should be added that can bring you back to the anchor. Here again, there are different styles: adding it before or after the note. It has never been a thing in print, and there is no standard. Also different characters are used for it. Common ones are ↵ and ↑. In any case, the anchor seems to be in need of an aria-label, which should be translatable.

I’m a bit torn on what to do here. We could either save the list in the post content, or dynamically add it to PHP.

I do see the list as derived data, so in that regard it doesn’t make sense to me to store it in the post content. In addition some parts need translation.

But I also see the list as a fallback mechanism if the theme doesn’t have any logic to position them elsewhere. I also don’t really see much of a problem with the list not being dynamically added. Once the post is written and published, it shouldn’t change anyway.

My suggestion is:

<!-- Note for uncollapsed selection -->
Hello <a id="{ id }-anchor" class="note-anchor" href="#{ id }" aria-labelledby="note">world</a>.

<!-- Note for collapsed selection -->
Hello world<a id="{ id }-anchor" class="note-anchor" href="#{ id }" aria-labelledby="note"></a>.

[…]

<!-- Add dynamically or to post content? -->

<footer>
	<h2 id="notes">Notes</h2>
	<ol>
		<li><a id="{ id }" href="#{ id }-anchor" aria-label="?">↑</a> A note about the world.</li>
	</ol>
</footer>

First Version

• I decided not to make the note list at the bottom editable for now, but each note is linked to the source where it can be edited. We could add this enhancement in the future if there is demand.

How has this been tested?

Screenshots

Types of changes

Checklist:

• My code is tested.
• My code follows the WordPress code style.
• My code follows the accessibility standards.
• My code has proper inline documentation.
• I've included developer documentation if appropriate.

[mtias]

There are three possible ways to position footnotes.

I wonder if this could be a property of the block that shows the footnotes at the bottom.

[mtias]

This is a great start!

The numbering should be added in CSS. Numbering is just a stylistic choice when using endnotes.

I tend to agree. Though it does leave the question of "how would this be represented on an email / RSS context?".

I decided not to make the note list at the bottom editable for now

Bidirectional editing would interesting to have, but agree with keeping it simple at first. Just focusing and opening the relevant footnote in the main content block seems like a good start.

For now the note can be edited in a plain textarea, but the note can contain HTML. In the future we could put it in a RichText area.

Was there any issue with using RichText there?

[ellatrix]

I tend to agree. Though it does leave the question of "how would this be represented on an email / RSS context?".

I've inserted inline CSS styles in the footer, so it should still work. :) Needs to be tested of course.

Was there any issue with using RichText there?

Yes. RichText only works within blocks right now, it relies on a lot of block context. See #15212.

[mapk]

The first is probably the most common way in print, but the latter seems to become more popular on the web.

@ellatrix can offer variations for the notes? Can we allow the author to select the preference? Maybe not for version one, but worth keeping in mind for a future iteration. I particularly like displaying them at the bottom of the page to start.

I’m a bit torn on what to do here. We could either save the list in the post content, or dynamically add it to PHP.

It would be great to see the list appear in the post content at the bottom and be editable. This would be a block that is fixed to the bottom maybe and doesn't allow anything to be added after it? I'm not entirely sure. Some design help is needed here.

For now the note can be edited in a plain textarea, but the note can contain HTML. In the future we could put it in a RichText area.

I like this. Often times notes should be allowed to link off to the source.

[ellatrix]

I discussed this PR quite a bit with @mcsf. We didn't really reach any definite conclusion, but here are some thoughts:

Can we allow the author to select the preference?

I don't think we should. I think it should be a theme thing.

We could either save the list in the post content, or dynamically add it to PHP.

I think the footnotes should be dynamical generated in PHP, defaulting to accumulating before any "next page" tags, and the end of the content. We could allow filtering, e.g. you could accumulate them before each h2 or something like that. The dynamic generation means that we need to do some HTML matching for the notes, similar to how WordPress core currently replaces static images with dynamic sources etc.

I think I now know enough to be able to finish the PR.

[karmatosed]

@ellatrix I'd love to give some design feedback once you've iterated a bit, as that sounds like your next step.

[ellatrix]

@karmatosed It's welcome at any point. :)

[karmatosed]

This is really great to interact with, huge props for all the work so far. In walking through I do have a few bits of feedback:

• Should note in toolbar be called footnotes? It took me a moment to find it.
• The hover in content cursor seems to not be that of a link. It is in the footer.
• I wonder if the note input could be larger? I don't see why it should be so narrow if the output area isn't.
• I really think there should be an easier way of removing the footnotes, it really took me a little time to work out I had to go into the toolbar and then unclick. Could it be like the link and if you are over an area with a note show in toolbar to 'unlink'?

[ellatrix]

@karmatosed Thanks for the feedback.

• Since they could be displayed anywhere by the theme, I decided to name it more generally. E.g. the theme could decide to have a pop up for the note on click/hover instead of rendering it at the bottom of the page. Perhaps "note" is slightly too general? But I like it... I'm can't find a good other name that doesn't include "foot". https://en.wikipedia.org/wiki/Note_(typography)
• I'm not sure what you mean here.
• Yes, good point, I'll make it bigger. :) I have some ideas to make it look better.
• I'm not entirely sure what you have in mind. You can just remove the note by pressing backspace? This was obvious in my mind, but it doesn't seem to be to others. I can also add a button to remove them.

[karmatosed]

I'm not sure what you mean here.

Sorry for the confusion. When I hover over the footnote link in text it has a different cursor to the one in the footer going to the source. It's hard to get a screenshot of but I can take a video if that doesn't explain.

I'm not entirely sure what you have in mind. You can just remove the note by pressing backspace? This was obvious in my mind, but it doesn't seem to be to others. I can also add a button to remove them.

Oh! This could totally be me but I didn't even think that would work. I'd be curious to see if that was just my mental model.

[SpinnerWebs]

@ellatrix Is there anything we can do to help with development or testing? Would like to use the feature; am loath to use a different footnote plugin if the facility may shortly be available in Gutenberg.

[romainmenke]

Any news on this 🙂
We noticed that #17824 was merged.
Maybe this is unblocked now?

[paaljoachim]

@ellatrix It would be nice to get this Foot notes PR added to WP 5.6. I went ahead and added it to the project board: https://github.com/WordPress/gutenberg/projects/48#card-45875045

[ellatrix]

I'll rework this PR. Have some alternative ideas.

[paaljoachim]

@ellatrix
Do you want to close this PR and use information from here in a new PR?

[alevals]

ant to close this PR and use information from here in a new PR?

Hello @ellatrix do you have any estimate on when this feature will be released?

[ellatrix]

Probably WP 5.7

[ellatrix]

Closing this in favour of #28261.