Bookmarks: part 1

[Witoso]

Goal

Create the first, minimal iteration of Bookmarks, so that users of the editor can create and edit them.

This will be later followed up by a ticket which will extend the linking experience to bookmarks.

Description

• Anchors/Bookmarks are one of the basic features of editors. They allow placing the specific marker to navigate someone to.
• We choose to name this feature Bookmarks, it’s a much more recognizable name for content creators. Its name and iconography are used in current popular content creation systems (Word, Google Docs).

Scope

• Functional requirements:
  • CRUD for Bookmarks in the editor, with a simple inline user interface (bookmarks will be shown in the text).
  • Bookmark creation should cover most places of the editor: text, blocks (images, tables), inline blocks, widgets.
  • We do only point-only-bookmarks, meaning you will not be able to wrap the text/elements and place a bookmark on them. We will create it as a singular <a id="xyz" aria-label="..."></a>.
    • The reasons are multiple: it’s less complex, as we don’t need to think about scenarios of a link in a link (it’s forbidden in HTML). Also, it’s less confusing for content creators, again the action of bookmarking with content that has a link leads to confusing results in the UI.
    • That means we need to figure out where the bookmarks will appear for the block elements. For simplicity, we decided for now to place them before block elements.
  • The UI for creation should not be confusing, especially in terms of selection. If we create point bookmarks, the creation point should be obvious.
• Non-functional requirements:
  • There shouldn’t be an observable performance penalty for bookmark creation (validation of duplicated ID).
  • Bookmarks are accessible.
  • Users coming with data <a id="xyz"></a> with GHS, should have their a migrated to the bookmarks UI.
  • Uncover the tricky technical parts for further development (how pagination works, validation of names/duplicates).
  • Should work in a collaboration session, track changes, revision history.
• Non-goals for this part
  • Handling wrapping bookmarks/anchors. <a id="xyz">This text is in the bookmark.</a>
    • We need to decide in the follow-ups how we want to handle such content. Opt-in, opt-out for migration?
  • Smaller sub-features, like copy URL/name of the Bookmark, toggling visibility of bookmarks, are not needed now. (nice to have)
  • Interaction with other features (slash commands, document outline).
  • Linking to bookmarks will be done in a separate part.
  • Pasting bookmarks from Word/Gdoc.

Prototypes

[sonfd]

Hello! This will be a great feature! Thank you for adding it.

I'm no expert, but I have been wondering about using <a id='my-bookmark'></a> as the markup for a bookmark, particularly with no option to have text inside the bookmark. I stumbled on the following pages that basically recommend against that markup. I just want to post them here in case they're useful for you.

1. Stack Overflow Answer to "WCAG Anchor Link": https://stackoverflow.com/a/23749088/6335551
2. Are your anchor links accessible? - while this article focuses on both the link and the bookmark, it seems useful nonetheless.
3. This related issue in the Drupal community: Create anchors using span tag rather than anchor tag

Thanks again for adding this feature!

[eckmo]

Related to the comment @sonfd left, but I'm working with a module in Drupal that does exactly this - extends CKEditor to allow for anchors. The module creates the anchor with a tags, which are then rendered as an a tag without href. While this is technically correct as it's semantically the same as a span, I believe using a span directly would be the better option here.

I documented the reasoning a little better in the Drupal module's issue queue, but an a tag without an href flags in certain accessibility checkers, such as the ARC Toolkit, which may create issues in the long run.

In my specific use case the anchor a tags were taking on our site's link styles as well (styles applied to all a tags), which was creating confusion for users as these aren't links. Adding a:not([href]) to undo the styles certainly works, but a span would alleviate the need altogether.

In addition to this, the language on the MDN page regarding a tags makes plenty of reference to href in association with a tags, and refers to them as 'links' a lot, implying that a link is comprised of an a tag and its href, with link text indicating the link's destination.

So TL;DR for accessibility and 'seems logically correct' reasoning, I believe a span is better suited for an anchor than an a tag.

Stoked to have this featured directly in CKE!

[Witoso]

Thanks so much for sharing your thoughts! Firstly, the description above could have been a bit more precise. We plan to implement Bookmarks as a fully accessible a element, so initially we planned something like <a id="xyz" aria-label="..."></a>.

We also read before we started a few materials on this, also the ones that were linked above 😊

There's always a question of how the role should be defined in the editor vs output content. In the editor, the bookmark will be interactive, so maybe some role="button" makes sense. Is it presentation in the published content? To be decided.

a tag without an href flags in certain accessibility checkers, such as the ARC Toolkit, which may create issues in the long run.

It shouldn't be tagged, as we will provide an accessible label.

In my specific use case the anchor a tags were taking on our site's link styles as well.

Good point! Should not happen, as bookmarks are planned to be empty elements. Of course, someone could have a global margins/paddings targeting this element, but the same goes for span? But fair point, targeting general a may be more common than general span.

While this is technically correct as it's semantically the same as a span, I believe using a span directly would be the better option here.

I'm also worried about another perspective, let's call it a "recognizability". It is usually the a element that is used for such things throughout the systems. If you export GDoc, or copy from Word, you get the a's. We often get feedback that our HTML standardization is too opinionated, so there's that too. 😅

Curious about your thoughts, @Comandeer and @pszczesniak.

[Witoso]

Also, important to mention that this:

<h2 id="introduction">Introduction</h2>
<a href="#introduction">#</a>

is another feature that we will plan for the future. It relates to providing auto-ids for the blocks in the editor (and auto-linking). We don't plan to focus on this part in Bookmarks to not increase the scope too much.

[Comandeer]

I don't see an issue with an empty link with only the id attribute – as it's already been mentioned, it's a known and established convention for marking up anchors (although linking to existing elements with the id attribute is even the more known one and IMO much better – as we do not clutter the HTML with extraneous elements).

I've checked what ARC Toolkit alerts for the a element without the href attribute and I would treat it as a false positive – as it references the WCAG's 2.2 Success Criterion 2.1.1 Keyboard. In this case, the element does not need to be keyboard-operable. In fact, it shouldn't be focusable at all as it's only used to mark a certain location in the document. We do not want it to be clickable (as it does not do anything or navigate anywhere) or even visible on the page. That also means it shouldn't have any label.

At least in the editor's output. The situation is quite different in the case of editing. For the editing, we probably want to make it focusable and clickable to allow in-place editing of the bookmark's settings (e.g. displaying a popup that allows to change the id attribute's value). In that case, we need to specify some ARIA role. According to the ARIA specification, the aria-label attribute cannot be added to the a element without the href attribute unless its role is explicitly changed to the one that allows this attribute. Probably the button one is the safest choice.

To sum up:

• for the output: <a id="anchor-name"></a>,
• for the editing part: <a id="anchor-name" role="button" aria-label="Edit bookmark anchor-name"></a>.

[niegowski]

For the editing part, we used our inline widget (the same as the inline image). While an inline widget is selected, the DOM selection is moved to the fake selection container, and the text "{bookmarkId} bookmark widget" is selected there. @Comandeer do we need to add the role and aria-label there?

[Comandeer]

If the element is correctly announced by the screen reader when the selection changes (and AFAIK it is for widgets), then it's ok and we do not need to add an additional label.