Add Aria-label support for better accessibility

This at the moment is mostly a “request for feedback” post. I am trying to learn about web accessibility with things like aria-labels and tab-focus so that people with e.g. screen readers can enjoy the websites we build as well.

A lot of that comes down to templates (I’m working on a theme with support for this), but there also needs to be support for that in the markdown rendering so that e.g. the generated page contents are focusable and findable for screen readers.

This is a pretty tricky topic I think, and I expect to do most of the work on this myself, but I’m hoping that someone who knows more about this can weigh in on how to best handle this.

My current ideas are just to give headings the correct aria-label and skip-links so you can go between headings more easily, and making things like


  • focusable in order (i.e. tabIndex=“0”)

    Does anyone have feedback on this idea?

  • I’m really not sure what you’re asking about or proposing. You seem to have some nebulous idea of something to do, but I haven’t figured out just what it is.

    General remarks to the things you have said:

    • ARIA attributes in general should be avoided: you should do things the natural way of the web instead, which normally yields better accessibility. If you don’t know what you’re doing, adding ARIA attributes is likely to make things worse than doing nothing. For the specific case of heading anchor links, an aria-label is justified, and is present in the default template (though I’m not fond of its text).

    • Setting tabindex is normally the wrong thing to do. There are definitely cases where you need to do it, but every last one of them that I can think of is only applicable when JavaScript is running, and actively managing focus in some way. tabindex="-1" in static content is just not something that should be done.

    So… can you elucidate on what you mean and are proposing?

    sorry for the unclear post. The idea I’ve been thinking about is mostly this:

    Without adding a tabIndex, most of the text on a page is not focusable by default which means that if there are other things that interact with your tab index such as links, then the website becomes very hard to navigate without using a mouse which is an accessibility issue. So what I am looking for is mainly a way to insert links specifically for screen readers like skip-links. This could be done at the markdown level, but I’m not very fond of that idea. Currently, I’m wondering if there is some way to (optionally) add this to the safe filter.

    As for your more specific points:

    • Zola doesn’t have a default template as far as I am aware, so could you specify which template you mean?
    • It is true that using semantic HTML is better than manually using stuff like aria but I still think that there are a few places where adding them could improve things. I know that it’s easy to bork things up which is why I’m asking for feedback here.
    • Static doesn’t mean “no javascript”. There is plenty of js baked into Zola, so while I agree that there should be an opt-out if you don’t want it because you don’t want js, I don’t think that’s an idea we should just throw out.
    • I actually didn’t say anything about setting tab indices to anything other than 0. There are definitely ways that adding a tabIndex="0" can make navigation a lot easier because without it jumping between headings can be a real slog and currently there is no way to add those things to things that are generated from markdown, which is what I want to address.

    Does that make sense? Hopefully, I’ve explained this a bit better now :slight_smile:

    What do you mean? The only embedded JS in Zola is the livereload.js used in zola serve.