Recently, NautArch edited my answer and "Adjusted headers for screenreader readability".
Largely this consisted of changing the one-hashtag heading [#] to two hashtags [##] and then progressively adding one further to each of the sub-headings.

A bit before that, V2Blast "fixed header formatting (for accessibility)" in my answer. This included removing bolding [** **] for subsection headers and replacing it with hashtags [###].

I appreciate these edits, but what would be even better would be a style guide explaining what format I should have used to begin with, so that I was not occupying the valued time of site editors.

The Markdown help page explains what we can do, but I think we need a page showing what we should do, and if one does not already exist, then perhaps here as a community wiki answer to this question.

In the course of the auto-review of this question, Use real headers instead of fake headers was suggested as a similar question (although I did not see it in my initial searches on "screenreader" and "readability"). That's one suggestion, but could we have a compiled list of them, linked to the individual how's and why's?


1 Answer 1


First of all, remember you can click on tags to see all the things tagged with them: is probably the best extant resource we have on this subject.

Beyond that, here are a few best practices off the top of my head. You’ll note that every one of these has some practical problems, however...

  • MathJax is bad for many screen-readers; at least one very popular screen-reader cannot read it.

    • This can vary a lot depending on which screen-reader you’re actually using, though.
  • Markdown tables are therefore much superior to using \begin{array}. Markdown tables have pretty nice screen-reader support.

    • Markdown tables, however, also have a smaller font size. Readers with poor eyesight can have a difficult time reading them. This is effectively “two steps forward, one step back,” which sucks.
  • Abusing code formatting to create “tables” of preformatted text is really bad, too—screen-readers will just read the words sequentially, and give no indication of the spacing or how they line up with one another.

  • Bare URLs are bad, per @Laurel, which is easy to understand with a moment’s consideration: recognizing a URL and skipping over the blue text is easy with your eyes, but listening to the computer say “double-u double-u double-u dot example dot com slash something slash another dash thing dot pee dee eff” is awful (and that’s for a relatively short and simple URL). Always use hyperlinks with some actually-descriptive text in them (“click here” is considered a bad practice even ignoring accessibility issues).

  • Images (in the context of the bodies of our questions or answers) should basically always have an alt property, which in the context of Markdown, means

    ![You need to put some meaningful text in here][1]

    The alt property is read by screen-readers as a description for the image, and should describe the image in enough detail that someone hearing it will be able to understand what the image includes that is important in the context of the question or answer. There is no limit to the size of alt properties, and remember a picture is worth a thousand words: you can get lengthy with this.

    In practice, describing images is hard. More often, alt properties are just a brief description of what the image is, not an actual description of the image itself. This is, in many contexts, probably good enough—certainly better than nothing—but it’s not the ideal.

  • Headings are ... the way Markdown is deployed on SE is not really right for what headings are supposed to be, for accessibility.

    For the unfamiliar, HTML headings have levels, from 1 which is largest, to 6, which is smallest. In HTML, these are created using tags, e.g. <h2>Heading</h2>; in Markdown, they’re created with an equal number of hashtags, as in ## Heading. These headings are extremely important for keyboard navigation (which is used with a screen-reader, but could also be used without one), as the preferred way of navigating is to jump from one heading to the next to find the section you want.

    The accessibility standards for the web say that each HTML page should have one (1) h1 (i.e. #), which indicates the subject of the page. SE (appropriately) uses this for the question title, for example. The problem is, it should be the only one; # shouldn’t (properly) be even allowed for answers. Moreover, every section of the page should have its own header, so every answer should start with an h2 (i.e. ##), and that should likewise be the only h2 in the answer. So answers should have a mandatory “title” field or similar, that gets h2, and then h3 (i.e. ###) should be the highest heading allowed in the body.

    This would you to go to the h1 to get the point of the page, then go “into” that page to read each of the h2/##s (each answer), and then (when you hear a heading you are interested), go “into” that answer and read/hear about whatever it has (including its own subsections as h3/### or less). That is how the web accessibility standards say things are supposed to go.

    Obviously, that’s not the reality on this site, and it probably never will be. Answers often don’t start with a header (of any size), may not even use a header at all. Many use only h2s, but use multiple, so there isn’t one big header over the whole answer. Others may use an h1, or even multiple, the same way. Or h3s. None of these meet the standards. It’s not at all clear to me which, if any, of these non-standard heading layouts is best. It’s also not clear to me that it’s particularly helpful to try to make specific contributions fit within it, when the prescribed heading-based mode of navigation simply isn’t going to work on the site since that isn’t the layout we have. It seems to me that those that want to use keyboard navigation are going to have to use a different system anyway.

    I am reaching out to some folks that are interested in accessibility and may know more than I do, to see if they have an opinion on this.

  • \$\begingroup\$ MathJax should be reserved for Math anyway. Do you have good recommendations for citations? \$\endgroup\$
    – Trish
    Commented Aug 10, 2023 at 8:31
  • \$\begingroup\$ @Trish No, Markdown does not support anything for citations that makes them more accessible (for anyone, really). Maybe a heading before footnotes indicating that they are footnotes would help somewhat? But other than that, it doesn’t matter what you do—it’s not going to be very good. \$\endgroup\$
    – KRyan
    Commented Aug 10, 2023 at 13:08
  • 1
    \$\begingroup\$ Don't forget about links! Not only should you not use bare URLs, you should make sure the text they link to is descriptive. Also, avoid empty links, including when there's an image with no alt inside (that is, [![][1]][1] is bad). \$\endgroup\$
    – Laurel
    Commented Aug 14, 2023 at 23:52
  • 1
    \$\begingroup\$ As for MathJax, it very much depends what you're using it for (and possibly the settings enabled on the screenreader, which will often ignore or misinterpret certain special characters if you use them in regular text). For example, it's great for exponents, since it will say something like "two cubed" while <sup> will be ignored: "two three". However, it says the word "math" at the end of every MathJax block, so using MathJax to format individual numbers is irritating. (Tested on VoiceOver iOS.) \$\endgroup\$
    – Laurel
    Commented Aug 15, 2023 at 0:12
  • 1
    \$\begingroup\$ @Laurel VoiceOver is doing better than NVDA, then. Unfortunately, NVDA is the most commonly used option on Windows, being free. \$\endgroup\$
    – KRyan
    Commented Aug 15, 2023 at 1:35

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .