Links to sub-documents: <span> element not rendered and not keyboard-accessible

[cyberbaloo]

Observed behavior

Links to sub-documents are implemented using <span type="button"> elements. These elements are neither rendered by screen readers nor accessible via keyboard. The type="button" attribute is invalid on a <span>. This error is present in the Docs.

Expected behavior

Links to sub-docs must be marked up with the <a href="url"> element to be rendered by assistive technologies, focusable via keyboard, and activatable with the Enter key.

Steps to reproduce

1. Open one of the affected pages
2. Locate a link to a sub-document
3. Attempt to reach it via keyboard using the Tab key
4. Notice that the element is not focusable
5. Navigate with a screen reader in link navigation mode
6. Notice that the element is absent from the links list

Possible solution

<!-- Before -->
<span type="button">Sub-document name</span>

<!-- After -->
<a href="/url/of/sub-document">Sub-document name</a>

Additional context / Screenshots

The type attribute is invalid on a <span> element. Only the <a href> element natively guarantees keyboard focusability, rendering in screen reader link lists, and activation via the Enter key. Adding role="link" and tabindex="0" to a <span> would be an insufficient and not recommended workaround.

RGAA criteria

Critère 6.1 : Chaque lien est-il explicite ?

Impact

A blind user navigating with a screen reader or a user navigating via keyboard cannot access the linked sub-documents. The functionality is entirely inaccessible without a mouse on the four affected pages.

Priority

P0

[Ovgodd]

Hi @cyberbaloo ,

I first implemented exactly what you recommended: a native <a href="/url/of/sub-document">. However, this creates an incompatibility with tiptap (the rich text editing engine that our BlockNote editor is built on). The drag and drop of blocks breaks when an <a> tag is present inside an inline content node.

Here is a video showing the bug, the link icon disappears after moving a block:

20260608-0928-58.2761819.mp4

Our closest alternative approach:

<span role="link" tabindex="0">Sub-document name</span>

This gives us:

• Focusable via Tab
• Announced as "link" by screen readers and present in the links list
• Activatable with Enter and Space (dedicated keyboard handler)
• Visible focus indicator on keyboard navigation
• No more invalid type="button" in the DOM

Wdyt @AntoLC ? or should we make a ticket on BlockNote side ?