Enhancing The Accessibility Of Your Markdown

No Comments

Markdown is a small textual content to HTML conversion language. It was created by John Gruber in 2004 with the purpose of constructing writing formatted textual content in a plain textual content editor simpler. You could find Markdown in lots of locations on the web, particularly in areas the place builders are current. Two notable examples are feedback on GitHub and the supply code for posts on Smashing Journal!

How Markdown Works

Markdown makes use of particular preparations of characters to format content material. For instance, you possibly can create a hyperlink by wrapping a personality, phrase, or phrase in sq. brackets. After the closing sq. bracket, you then embrace a URL wrapped in parenthesis to create a vacation spot for the hyperlink.

So typing:

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

Would create the next HTML markup:

<a href=”https://www.smashingmagazine.com/”>I’m a hyperlink</a>

You can even mix HTML with Markdown, and it’ll all boil all the way down to HTML when compiled. The next instance:

I’m a sentence that features <span class=”class-name”>HTML</span> and __Markdown__ formatting.

Generates this as HTML markup:

<p>I’m a sentence that features <span class=”class-name”>HTML</span> and <sturdy>Markdown</sturdy> formatting.</p>

Markdown And Accessibility

Accessibility is a holistic concern, that means that it impacts each facet of making and sustaining digital experiences. Since Markdown is a digital software, it additionally has accessibility issues to concentrate on.

The excellent news:
Markdown generates easy HTML markup, and easy HTML markup may be simply learn by assistive expertise.
The much less excellent news:
Markdown isn’t all-encompassing, neither is it prescriptive. As well as, there may be extra to accessibility than simply assistive expertise.

Relating to making certain your Markdown content material is accessible, there are two big-picture points:

There are specific sorts of content material Markdown doesn’t assist, and
There isn’t a Clippy-esque expertise to accompany you when you write, that means that you simply gained’t get a warning should you do one thing that may create inaccessible content material.

Due to these two issues, there are issues we are able to do to make sure our Markdown content material is as accessible as it may be.

The Three Most Vital Issues You Can Do

It may be tough to know the place to start out on the subject of making your content material accessible. Listed here are three issues you are able to do proper now to make a big, vital influence.

1. Use Headings To Define Your Content material

Navigating by heading is by far the preferred technique many assistive expertise customers use to grasp the content material of the web page or view they’re .

Due to this, you need to use Markdown’s heading formatting choices (# , ##, ###, ####, #####, and ######) to create a logical heading construction:

# The title, a first-level heading

Content material

## A second-level heading

Content material

### A 3rd-level heading

Content material

## One other second-level heading

Content material

This creates a hierarchical define that’s simple to scan:

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

Writing efficient heading ranges is a little bit of an artwork, in that you really want sufficient data to speak the general scope of the web page, however not overwhelm somebody by over-describing. For instance, a recipe may solely want a number of h2 parts to part the elements, directions, and backstory, whereas an instructional paper may want all six heading ranges to completely talk nuance.

Having the ability to shortly scan all of the headings on a web page or view and leap to a selected one is a way that isn’t restricted to simply display screen readers, both. I take pleasure in and profit from extensions reminiscent of headingsMap that allow you to make the most of this characteristic.

2. Write Significant Alternate Descriptions For Your Pictures

Alternate descriptions assist people who’ve low imaginative and prescient or are shopping with photographs turned off to grasp the content material of the picture you’re utilizing.

In Markdown, an alternate description is positioned in between the opening and shutting brackets of the picture formatting code:

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

An alternate description ought to clearly and concisely describe the content material of the picture and the context of why it was included. Additionally don’t neglect so as to add punctuation!

Sure web sites and internet apps that use Markdown enter may also attempt to add alternate description textual content for you. For instance, GitHub will use the title of the file you add for the alt attribute:

Sadly, this doesn’t present sufficient context for an individual who can’t see the picture. On this state of affairs, you need to talk why the picture is vital sufficient to be included.

Examples of this you’ll generally see on GitHub embrace:

A visible bug, the place one thing doesn’t look the way in which it’s alleged to,
A brand new characteristic that’s being proposed,
An annotated screenshot offering suggestions,
Graphs and flowcharts that specify processes, and
Response GIFs for speaking emotion.

These photographs aren’t ornamental. Since GitHub is public by default, you don’t know who’s accessing your repo, or their circumstances. Higher to proactively embrace them.

For those who need assistance writing alternate descriptions, I’d enthusiastically suggest the W3C’s alt Resolution Tree and Axess Lab’s Final Information to Alt Texts.

3. Use Plain Language

Easy, direct language helps everybody perceive your content material. This contains individuals:

With cognitive issues,
Who don’t use English as their main language,
Unfamiliar with the ideas you’re speaking,
Who’re careworn or multitasking and have restricted consideration spans,
And so forth.

The simpler it’s for somebody to learn what you write, the simpler it’s for them to grasp and internalize it. This helps with each type of written Markdown content material, be it weblog posts, Jira tickets, Notion notes, GitHub feedback, Trello playing cards, and so forth.

Think about your sentence and phrase lengths. Additionally, contemplate who your supposed viewers is, and take into consideration issues just like the jargon and idioms you employ.

For those who need assistance simplifying your language, three instruments I like to make use of are Hemingway, Datayze’s Readability Analyzer, and the xkcd Easy Author. One other website price testing is plainlanguage.gov.

Different Concerns

Need to go the additional mile? Nice! Listed here are some issues you are able to do:


Along with offering alternate descriptions, there are a number of different issues you are able to do to make your Markdown-inserted photographs accessible.

Mark Up SVG Pictures Correctly

SVG is a superb format for graphs, icons, easy illustrations, and other forms of images that makes use of easy shapes and crisp strains.

There are two methods to render SVG in Markdown. Each approaches have particular stuff you’ll must be looking out for:

1. Linking to a picture with a .svg file extension

Word: The bug that I’m about to explain has been fastened, nonetheless, I’m nonetheless recommending the next recommendation for the following couple of years. This is because of Safari’s questionable tactic of tying browser updates to system updates, in addition to hesitancy round updating software program for some individuals who use assistive expertise.

For those who’re linking to an SVG as a picture, you’ll need to use HTML’s img component, and never Markdown’s picture formatting code (![]()).

The explanation for that is that sure display screen readers have bugs once they attempt to parse an img component that hyperlinks to an SVG file. As an alternative of asserting it as anticipated as a picture, it would announce it as a gaggle, or skip asserting the picture fully. To repair this, declare function=”img” on the picture component:

alt=”A sylized sunflower.”
src=”flower.svg” />

2. Utilizing Inline SVG Code

There are a number of causes for declaring a picture as inline SVG code as a substitute of utilizing an img component. The explanation I most frequently encounter is to assist darkish mode.

Very like with utilizing an img component, there are a few attributes you have to embrace to make sure assistive expertise interprets it as a picture, and never code. The 2 attribute declarations are function=”img” and aria-labelledby:

viewBox=”0 0 90 54″
<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. 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’ll additionally need to make sure you use a title component (to not be confused with the title attribute) to explain the picture, much like an img component’s alt attribute. Not like an alt attribute, you’ll additionally must affiliate the id of the title component with its mother or father svg component by utilizing aria-labelledby.

For those who’d prefer to go deeper on accessibly marking up SVG, I like to recommend Accessible SVGs by Heather Migliorisi, and Accessible SVGs: Excellent Patterns For Display Reader Customers by Carie Fisher.

Load With Animated Pictures Paused

Animated GIFs are one other widespread factor you’ll discover with Markdown content material — I discover them as a rule being utilized by a developer to specific their delight and frustration when discussing a technical matter.

The factor is, these animations may be distracting and adversely have an effect on somebody who’s making an attempt to learn by means of your content material. Cognitive issues reminiscent of ADHD are particularly affected right here.

The excellent news is you possibly can nonetheless embrace animated content material! There are a number of choices:

Use the image component, utilizing filetypes reminiscent of .mp4 and .webm that may load in a paused state, or
Use an answer that provides play/pause performance to a .gif, reminiscent of Steve Faulkner’s particulars/abstract hack, or the freezeframe.js library.

This little element can go a protracted option to serving to individuals out with out having to desert a means so that you can categorical your self.


For those who write content material on-line, eventually you’re going to have to make use of hyperlinks. Listed here are some issues to concentrate on:

Use Distinctive, Descriptive Hyperlink Names

Some types of assistive expertise can navigate by means of an inventory of hyperlinks on a web page or view the identical means they’ll navigate by means of headings. Due to this, you need your hyperlinks to trace at what somebody can anticipate finding in the event that they go to it.

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

You’ll additionally need to keep away from ambiguous phrases, particularly in the event that they repeat. Phrases like “click on right here” and “study extra” are widespread culprits. These phrases don’t make sense when separated from the context of their surrounding non-link content material. As well as, utilizing the time period greater than as soon as can create experiences like this:

Keep away from Opening Hyperlinks In A New Tab Or Window

Sure variants of Markdown reminiscent of Kramdown can help you write code that may open hyperlinks in a brand new tab or window:

[link name](url){:goal=”_blank”}

Doing this creates a safety threat. As well as, this expertise is so complicated and undesirable that it’s a Internet Content material Accessibility Tips (WCAG) success criterion. It is much better to let everybody utilizing your web site or internet app make the selection for themselves about whether or not or not they need to open a hyperlink in a brand new tab.

Use Skip Hyperlinks With Discretion

A skip hyperlink, or “skipnav” is a option to bypass giant sections of content material. You’ll generally encounter them as a option to bypass the brand and predominant navigation on a webpage, permitting somebody to shortly leap to the primary content material.

That is additionally an important approach for permitting somebody to bypass a “keyboard entice,” one thing generally present in embedded content material.

Keyboard traps are the place somebody who isn’t utilizing a mouse or a touchpad can’t escape an interactive element as a result of how it’s constructed. You’ll sometimes discover these with embedded iframe widgets.

A great way to check for keyboard traps? Use the Tab key!

With no skip hyperlink, somebody utilizing assistive expertise could must resort to refreshing the web page or view to flee the entice. This isn’t nice and is particularly troubling if motor management issues are thrown into the combo. I’m of the varsity of thought that most individuals will simply shut the tab in the event that they run into this state of affairs, fairly than attempt to wrestle with getting it to work.

Along with his nice submit about testing with the Tab key, Manuel Matuzović tells us about his use of skip hyperlinks, in addition to different enhancements in Enhancing the keyboard accessibility of Embedded CodePens.

Be Cautious With Routinely Generated Heading Anchor Hyperlinks

Some Markdown turbines robotically add an anchor hyperlink to accompany every heading you write. That is so you possibly can focus somebody’s consideration to the related part on a web page or view when sharing content material.

The difficulty is there is likely to be some assistive expertise points with this, relying on how this anchor hyperlink is constructed. If the anchor hyperlink is just wrapped round a glyph reminiscent of #, ¶, or §, we run into two points:

The hyperlink’s title doesn’t make sense when faraway from its surrounding context, and
The hyperlink’s title is repeated.

This situation is mentioned in additional element by Amber Wilson in her submit, Are your Anchor Hyperlinks Accessible? Her submit additionally goes into element about totally different options, in addition to their potential drawbacks.

Point out The Presence Of Downloads

Many of the instances hyperlinks take you to a different web page or view. Typically, nonetheless, the vacation spot is a obtain. When this occurs, the browser both:

Opens an app related to the request file sort to show it, or
Prompts you to reserve it to the Working System’s filesystem.

These two experiences may be jarring, particularly should you can’t see the display screen. A great way to forestall this less-than-ideal expertise is to trace on the presence of the obtain within the hyperlink’s title. For instance, right here’s how you’d do it in Markdown when linking to a PDF:

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


Coloration isn’t associated to Markdown per se, however it does have an effect on numerous Markdown-generated content material. The most important color-related issues are issues you possibly can normally modify in case you are utilizing a running a blog service reminiscent of WordPress, Eleventy, Ghost, Jekyll, Gatsby, and so forth.

Use A Darkish Mode Theme

Offering a toggle for darkish mode permits somebody to decide on an expertise that helps them learn. For some, it might be an aesthetic choice, for others it might be a option to keep away from issues like migraines, eye pressure, and fatigue.

The vital bit right here is alternative. Let somebody who has darkish mode turned on use mild mode on your web site, and vice-versa (and ensure the UI to take action is accessible).

The factor is, you possibly can’t know what an individual’s wants, needs, or circumstances are once they go to your web site or internet app, however you possibly can present them with the flexibility to do one thing about it.

Let’s additionally do not forget that Markdown exports easy, simple HTML, and that’s simple to work inside CSS. This goes a protracted option to making your darkish mode theme simpler to develop.

Use Syntax Highlighting With Good Coloration Distinction Help

Markdown can create blocks of code by wrapping content material in triple backticks (“`). It may possibly additionally create inline content material wrapped within the code component by wrapping a personality, phrase, or phrase in single backticks.

For each examples, many individuals add syntax highlighting libraries reminiscent of PrismJS to assist individuals perceive the code instance they’re offering.

Sure themes use light-on-light or dark-on-dark values as an aesthetic alternative. Sadly, this implies the code could also be tough or not possible to see for some people. The trick right here is to pick out a syntax highlighting theme that makes use of coloration values which might be excessive sufficient distinction that individuals can really see each glyph of the code.

A option to decide whether it is excessive sufficient distinction is to make use of a software reminiscent of WebAIM’s and manually test the colour values supplied by the theme. For those who’re on the lookout for a sooner suggestion and don’t thoughts somewhat self-promotion, I keep a coloration contrast-friendly syntax highlighting theme.

Content material That Isn’t Supported By Markdown

Since you should utilize HTML in Markdown, there are specific sorts of content material you’ll see extra usually than others in Markdown. Listed here are a number of issues for a few them.

Use The title Attribute To Describe iframe Content material

HTML’s title attribute is usually misused to create a tooltip impact. Sadly, this causes numerous complications for assistive expertise customers, and its utilization this fashion is taken into account an antipattern.

The one good use of a title attribute is to supply a concise, significant description of what the iframe accommodates. This description offers assistive expertise customers a clue about what to anticipate in the event that they navigate into the iframe to take a look at its contents.

For Markdown, the commonest type of iframe content material will probably be embeds reminiscent of YouTube movies:

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

Very like your hyperlink textual content, you’ll additionally need to keep away from generic and repetitive title content material. YouTube’s embed code defaults to YouTube video participant, which isn’t so nice. We are able to do some higher and replace that to YouTube: Video title. This may particularly assist if there’s a couple of YouTube video embedded on the web page or view.

As to why YouTube does it this fashion when it already is aware of the video title data is one other drawback fully.

Present Captions And Transcripts For Movies And Recorded Audio

Talking of YouTube, one other factor you’ll need to do is guarantee your video and audio have captions and transcripts.


Captions show a textual content model of video content material in realtime as it’s being spoken, permitting somebody who biologically or circumstantially can’t hear audio to have the ability to perceive the video’s content material. Captions also can embrace sound results, music, and different cues which might be vital to speaking that means.

Hottest video internet hosting suppliers have options to assist captioning, together with displaying them in an embedded context. The vital half right here is to keep away from craptions—manually overview robotically generated captions to make sure they make sense to a human being.


Transcripts are caption’s sibling. They take all of the spoken dialog, pertinent sound results and music, and different vital particulars and record them exterior of the embedded video or audio. There are various advantages to doing this, together with permitting somebody to:

Learn by means of the video and audio content material at their very own tempo;
Modify the scale and presentation of the content material;
Print the content material out or convert it right into a format that’s simpler to digest;
Extra simply uncover the content material by way of search engines like google and yahoo;
Extra simply translate the content material.

Reader Mode

Like different Markdown-adjacent issues, Reader Mode can supply numerous advantages from an accessibility perspective.

If you’re unfamiliar, Reader Mode is a characteristic provided by many browsers that strips away every part apart from the primary content material. Most reader modes additionally present controls for adjusting the textual content measurement, font, line peak, foreground and background coloration, column width, even having your gadget learn the content material out loud for you!

You’ll be able to’t straight set off Reader Mode by utilizing Markdown. Longform Markdown content material, nonetheless, is usually rendered in templates that may be set to make them Reader Mode-friendly.

Mandy Michael teaches us how to do that in her submit, Constructing web sites for Safari Reader Mode and different studying apps. A mix of semantic HTML, sectioning parts, and a splash of structured microdata are all it takes to unlock this nice characteristic.

You Don’t Have To Do All the things At As soon as

It is a lengthy submit that covers totally different features of Markdown and the way it interacts with different expertise. It may possibly appear daunting, in that it’s numerous content material to cowl throughout a number of totally different topic areas.

The factor about accessibility work is that each little bit helps. You don’t have to deal with each consideration I’ve on this submit in a single massive, sweeping change. As an alternative, attempt choosing one factor to deal with, and construct from there.

Know that every tweak and replace can have a direct influence on somebody’s high quality of life when utilizing the online, and that’s enormous.

Proceed Studying on Smashing Journal

CommonMark: A Formal Specification For Markdown
Constructing A Node.js Specific API To Convert Markdown To HTML
Constructing Sample Libraries With Shadow DOM In Markdown

    About Marketing Solution Australia

    We are a digital marketing company with a focus on helping our customers achieve great results across several key areas.

    Request a free quote

    We offer professional SEO services that help websites increase their organic search score drastically in order to compete for the highest rankings even when it comes to highly competitive keywords.

    Subscribe to our newsletter!

    More from our blog

    See all posts

    Leave a Comment