Link Accessibility

Accessibility is hard and there are many ways of handling this for heading anchor links. Here are some examples of how you can handle link accessibility and these examples by no means guarantee that they will be fully accessible.

Adding text for screen readers

Most frameworks will have a CSS class intended to "make this text visible only to screen readers."

The anchorBody parameter accepts raw HTML and will be injected inside of every <a> that this snippet adds. In the example below, I am using Bootstrap's .sr-only class and FontAwesome's fa-link tag that is aria-hidden true.

You can also make use of the %heading% placeholder so that the link body contains the heading they are linking to.

{% capture anchor_body %}
    <span class="sr-only">Permalink to "%heading%"</span>
    <i class="fa fa-link" aria-hidden="true"></i>
{% endcapture %}

{% include anchor_headings.html html=text anchorBody=anchor_body %}

Using ARIA labels

Relying on a CSS class to exist may cause concerns for some. A common approach is to use aria-label or aria-labelledby for indicating the purpose of a link. Using aria-labelledby can be tricky with this snippet, so we'll stick to using aria-label.

{% include anchor_headings.html html=text anchorAttrs='aria-label="Permalink to %heading%"' anchorBody="#" %}

Hiding links entirely for screen readers

Lastly, maybe you just don't want your links to be read by screen readers. To achieve this, you can use aria-hidden and tabindex="-1" to hide these links and not make them focusable.

{% include anchor_headings.html html=text anchorAttrs='aria-hidden="true" tabindex="-1"' anchorBody="#" %}