Improving The Accessibility Of Your Markdown — Smashing Magazine

Markdown: A Quick Primer

Markdown is a lightweight markup language created by John Gruber in 2004 to simplify writing formatted text in plain text editors. It's widely used across the web, from GitHub comments to Smashing Magazine's own post sources.

The syntax relies on character combinations to structure content. For instance, wrapping text in square brackets and following it with a parenthesized URL creates a link:

[I am a link](https://www.smashingmagazine.com/)

Which compiles to standard HTML:

<a href="https://www.smashingmagazine.com/">I am a link</a>

Markdown also permits inline HTML, which passes through unchanged during compilation:

I am a sentence that includes <span class="class-name">HTML</span> and __Markdown__ formatting.

Produces:

<p>I am a sentence that includes <span class="class-name">HTML</span> and <strong>Markdown</strong> formatting.</p>

Accessibility Considerations

Because accessibility is a holistic concern, Markdown is not exempt. The generated markup is typically simple and screen-reader friendly, but Markdown is neither comprehensive nor prescriptive. There are no built-in guardrails to catch accessibility mistakes before publishing.

Two overarching challenges surface:

• Markdown cannot express certain content types.
• It lacks an interactive assistant to alert you to inaccessible output.

Despite these constraints, you can take actionable steps to improve the accessibility of Markdown-based content.

Three High-Impact Fixes

Use Headings as an Outline

Screen reader users navigate pages primarily through heading structure. Markdown's # through ###### syntax creates that hierarchy:

# The title, a first-level heading

Content

## A second-level heading

Content

### A third-level heading

Content

## Another second-level heading

Content

This renders as a scannable outline:

1. The title, a first-level heading
    a. A second-level heading
        i. A Third-level heading
    b. Another second-level heading

Heading levels are an art: enough structure to convey the page's scope without overwhelming detail. A recipe might only need a few h2 elements, while an academic paper could justify using all six levels. Tools like the headingsMap extension extend this navigation benefit beyond screen readers.

Provide Meaningful Image Alt Text

Alternate descriptions clarify an image's purpose for those with low vision or with images disabled. In Markdown, the alt text sits inside the bracket notation:

![A sinister-looking shoebill staring at the camera.](https://live.staticflickr.com/3439/3259412053_92f822bee2_b.jpg)

Alt text should concisely describe both content and context—and include punctuation. Some platforms, like GitHub, auto-populate the alt attribute from the filename:

That's rarely sufficient. Filenames lack the narrative context that matters. This is especially problematic on public repositories where you can't predict your audience. Common use cases—bug screenshots, proposed features, feedback annotations, process diagrams, reaction GIFs—are not decorative and need proper descriptions. The W3C's alt Decision Tree and Axess Lab's Ultimate Guide are excellent references.

Practice Plain Language

Direct, uncomplicated writing benefits nearly every reader: those with cognitive challenges, non-native English speakers, newcomers to your subject, anyone distracted, and beyond. The easier the text is to read, the easier it is to absorb.

Audit sentence length, word choice, and idiom usage against your audience's expectations. Hemingway, Datayze's Readability Analyzer, and the xkcd Simple Writer can all help streamline your prose, alongside the guidance at plainlanguage.gov.

Going Beyond the Basics

Once you have the essentials covered, there are additional layers of accessibility you can add to your Markdown content. These details often get overlooked but can make a substantial difference for people using assistive technology.

Handling Images With Care

Alt text is just the starting point for images. The way you implement an image in Markdown can have its own accessibility implications, especially with certain file formats.

SVG: Choose Your Markup Wisely

SVG is excellent for charts, icons, and simple illustrations. The way you render an SVG in Markdown, however, matters. If you link to an image file with an .svg extension, use HTML’s img element rather than Markdown’s image syntax (![]()). Certain screen readers can misannounce an img element pointing to an SVG, treating it as a group or skipping it entirely. Adding role="img" helps enforce the correct announcement:

<img 
  role="img" 
  alt="A sylized sunflower."
  src="flower.svg" />

Inline SVG code, which is sometimes used to support dark mode with CSS filters, requires a different approach. To ensure assistive technology doesn’t treat it as code, the svg element needs both role="img" and aria-labelledby:

<svg
  aria-labelledby="svg-title"
  fill="none"
  height="54"
  role="img"
  viewBox="0 0 90 54"
  width="90"
  xmlns="https://www.w3.org/2000/svg">
  <title id="svg-title">A pelican.</title>
  <path class="icon-fill" d="M88.563 2.193H56.911a7.84 7.84 0 00-12.674 8.508h-.001l.01.023c.096.251.204.495.324.733l4.532 10.241-1.089 1.09-6.361-6.554a10.18 10.18 0 00-7.305-3.09H0l5.229 4.95h7.738l2.226 2.107H7.454l4.451 4.214h7.741l1.197 1.134c.355.334.713.66 1.081.973h-7.739a30.103 30.103 0 0023.019 7.076L16.891 53.91l22.724-5.263v2.454H37.08v2.81h13.518v-.076a2.734 2.734 0 00-2.734-2.734h-5.441v-3.104l2.642-.612a21.64 21.64 0 0014.91-30.555l-1.954-4.05 1.229-1.22 3.165 3.284a9.891 9.891 0 0013.036 1.066L90 5.061v-1.43c0-.794-.643-1.438-1.437-1.438zM53.859 6.591a1.147 1.147 0 110-2.294 1.147 1.147 0 010 2.294z"/></svg>

You must also include a title element inside the SVG (not the title attribute) to describe the image, similar to an alt attribute. The aria-labelledby attribute then associates the title element’s id with the parent svg element.

Pause Animated Images by Default

Animated GIFs are common in technical writing, but the constant motion can be distracting for many readers, especially those with cognitive conditions like ADHD. You don’t need to remove them entirely—you can make them less disruptive:

1. Use the picture element with modern filetypes like .mp4 or .webm which can be configured to load paused.
2. Adopt a solution that adds play/pause controls, like a details/summary wrapper or a JavaScript library such as freezeframe.js.

Authoring Links for Accessibility

Links are your primary navigation tool within content. Their accessibility hinges on how you name them and how you get the browser to handle them.

Write Link Names That Stand Alone

Assistive technology users can navigate pages by scanning a list of links only, separate from the surrounding text. Use link text that clearly describes the destination:

Learn more about [how to easily poach an egg](https://lifehacker.com/this-is-the-chillest-easiest-way-to-poach-an-egg-1825889759).

Avoid ambiguous terms like “click here,” especially when used more than once. Without context, these phrases fail to communicate:

Don’t Force New Tabs

While certain Markdown flavors like Kramdown support attributes to open a link in a new tab, resist the temptation:

[link name](url){:target="_blank"}

Opening new tabs is a security risk and violates a WCAG success criterion. The user’s choice to leave your page is theirs to make.

Use Skip Links for Complex Embeds

Skip links aren’t just for heading straight to the main content over a navigation menu. They are also valuable for bypassing embedded content with lots of interactive elements, such as widgets or complex media:

This technique also prevents keyboard traps, where a user without a mouse gets stuck in a component and can’t escape. A regular Tab key test is the simplest way to find these issues. Without a way out, the only escape for many people is to refresh the page or leave entirely.

Anchor Links with Care

Many Markdown generators automatically generate anchor links for headings. Issues arise when the link text is just a glyph like #, ¶, or §. This results in link names that are both meaningless and repetitive. Ensure the accessible name of these links is descriptive, or hide the glyph from screen readers appropriately.

Flag Downloads Clearly

Links don’t always lead to another page. When pointing to a file download, the experience of a new app opening or a save prompt can be jarring if announced by a screen reader without warning. Forewarn users in the link text itself:

Download our [2020 Annual Report (PDF)](https://mycorp.biz/downloads/2020/annual-report.pdf).

Color and Theming

While not automatic parts of Markdown syntax, the themes you apply to your generated HTML impact its readability significantly.

Offer a Dark Mode Toggle

Dark mode isn’t just about style—it can prevent eye strain and migraines for some users. Provide a user-controlled toggle to switch between themes, letting each person choose the setting that works best for them. Since Markdown outputs straightforward HTML, implementing effective CSS themes is usually uncomplicated.

Check Syntax Theme Contrast

Many sites use libraries like PrismJS to visually analyze code blocks. Aesthetics are fine, but if your chosen theme uses low-contrast colors, it makes the text hard to read. Use a checker to verify the values, or start with a theme specifically built for accessibility if you prefer a quicker fix:

Non-Markdown Content

Markdown can embed HTML, so you will inevitably encounter content beyond simple text and links. A few key things can improve those experiences.

Describe iframes with title Attributes

The title attribute has valid uses beyond the commonly misused tooltip effect. One correct usage is to describe what an iframe contains. Be specific and avoid generic defaults, such as YouTube’s “YouTube video player.” A title like YouTube: AccessibleSVGs Tutorial is far more useful.

<iframe width="560" height="315" src="https://www.youtube.com/embed/SDdsD5AmKYA" title="YouTube: Accessibility is a Hydra | EJ Mason | CascadiaJS 2019." frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

Provide Captions and Transcripts for Media

Captions

Captions provide a synchronized, real-time text version of video content. They aren’t just for dialog; they also note key sound effects and music. If your video hosting platform auto-generates captions, they still require manual review to ensure accuracy before they’re usable.

Transcripts

Transcripts are the textual counterpart to multimedia, listing out conversations and significant audio cues separately from the video or audio player. This format offers significant value, allowing people to read content at their own pace, alter its size and layout, print it, find it via search, and even translate it more easily.

How Markdown Reaches Reader Mode

Reader Mode, present in most modern browsers, strips a page down to its primary content and hands control of text size, font, line height, colors, column width, and even read-aloud functionality to the user.

You cannot trigger Reader Mode directly from Markdown. But long-form Markdown content frequently lives inside templated layouts, and those templates can be engineered to cooperate with Reader Mode. Mandy Michael’s guide on building sites for Safari Reader Mode shows that semantic HTML, sectioning elements, and a bit of structured microdata are enough to make the feature work reliably.

Improvement Is Incremental

The topics covered here span several distinct areas—syntax, tooling, and the surrounding technologies that consume Markdown output. It would be unreasonable to treat all of it as a single checklist to complete in one pass.

Accessibility work compounds. You do not need to resolve every item at once; pick one aspect, adjust it, and move on to the next when you are ready. Each individual change has a measurable effect on how comfortably someone can use your content, and that alone justifies the slower, steadier approach.

Related Reading

• CommonMark: A Formal Specification For Markdown
• Building A Node.js Express API To Convert Markdown To HTML
• Building Pattern Libraries With Shadow DOM In Markdown
• The Importance Of Graceful Degradation In Accessible Interface Design