· Updated

Making Markdown Content Accessible

Creating accessible content isn't just about compliance—it's about ensuring everyone can engage with your ideas. Here's how to make your Markdown articles work for all users.

1. Structure and Headings

Use Proper Heading Hierarchy

# Main Article Title (H1)
## Major Section (H2)
### Subsection (H3)
#### Sub-subsection (H4)

Why it matters: Screen readers use heading structure to navigate content. Never skip heading levels.

Example of Good Structure

  • H1: “Introduction to Web Accessibility”
  • H2: “Visual Accessibility”
  • H3: “Color Contrast Guidelines”
  • H3: “Font Size Considerations”
  • H2: “Audio Accessibility”

2. Images and Media

Always Provide Alt Text

![A developer using a screen reader to navigate code](developer-accessibility.jpg)

<!-- Not just: ![](developer-accessibility.jpg) -->

Use Figures for Complex Images

<figure>
  <img src="chart-data.png" alt="Bar chart showing 65% increase in mobile usage from 2020 to 2024">
  <figcaption>Mobile device usage has grown significantly over the past four years</figcaption>
</figure>

Decorative vs Informative Images

  • Informative: Describe what the image conveys
  • Decorative: Use empty alt text (alt="") or skip in Markdown

Write Descriptive Link Text

<!-- Good -->
Read our [comprehensive accessibility guide](accessibility-guide.md) for more details.

<!-- Bad -->
For more details, [click here](accessibility-guide.md).

Visit the [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/) (external link) for official standards.

4. Lists and Content Organization

Use Proper List Types

<!-- Ordered list for sequences -->
1. Plan your content structure
2. Write accessible markup
3. Test with assistive technology

<!-- Unordered list for related items -->
- Screen readers
- Voice control software
- Keyboard navigation
- Magnification tools

Description Lists for Definitions

API
: Application Programming Interface - a set of protocols for building software

REST
: Representational State Transfer - an architectural style for web services

5. Code and Technical Content

Provide Context for Code Blocks

Here's how to add ARIA labels to a button:

```html
<button aria-label="Close dialog" onclick="closeModal()">
  ×
</button>


### Explain Abbreviations on First Use
```markdown
<!-- Good -->
Application Programming Interface (API) endpoints

<!-- Then later use -->
The API returns JSON data.

6. Tables

Always Include Headers

| Technology | Accessibility Feature | Support Level |
|------------|----------------------|---------------|
| Screen Reader | Text-to-speech | Excellent |
| Voice Control | Speech recognition | Good |
| Switch Access | Alternative input | Limited |

Complex Tables Need HTML

<table>
  <caption>Accessibility technology comparison</caption>
  <thead>
    <tr>
      <th scope="col">Technology</th>
      <th scope="col">Primary Users</th>
      <th scope="col">Cost Range</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th scope="row">JAWS</th>
      <td>Blind users</td>
      <td>$1,000+</td>
    </tr>
  </tbody>
</table>

7. Language and Readability

Use Clear, Simple Language

  • Prefer active voice: “We implemented…” not “It was implemented…”
  • Use common words: “help” instead of “facilitate”
  • Keep sentences under 20 words when possible

Define Technical Terms

**Semantic HTML**: HTML that uses elements according to their meaning, not just appearance. For example, using `<button>` for clickable actions instead of `<div>` with click handlers.

8. Audio and Video Content

Audio Content (Like This Article!)

---
hasAudio: true
audioFile: /audio/articles/accessibility-guidelines.mp3
audioTranscript: false
readingTime: 8
---

Video Considerations

<!-- Always mention if captions are available -->
Watch the [introduction video](intro.mp4) (includes captions and audio description).

9. Testing Your Content

Screen Reader Testing

  1. Install NVDA (free) or use built-in screen readers
  2. Navigate using only Tab, Enter, and arrow keys
  3. Listen to how content flows without looking

Keyboard Navigation Test

  • Can you reach every interactive element?
  • Is the focus indicator visible?
  • Does Tab order make logical sense?

Color Contrast Check

  • Use tools like WebAIM's contrast checker
  • Ensure 4.5:1 ratio for normal text
  • Ensure 3:1 ratio for large text

10. Quick Accessibility Checklist

Before publishing any article:

  • Proper heading hierarchy (H1 → H2 → H3)
  • All images have descriptive alt text
  • Links describe their destination
  • Lists use appropriate markup
  • Tables include headers
  • Technical terms are explained
  • Content works with keyboard navigation
  • Color isn't the only way to convey information

Conclusion

Accessible content benefits everyone. Users with disabilities get full access to your ideas, while all users enjoy clearer structure and better navigation.

Start with these basics, then gradually incorporate more advanced techniques. The goal isn't perfection—it's progress toward inclusivity.

This article follows its own accessibility guidelines. Notice the clear headings, descriptive links, and structured content that works with screen readers and keyboard navigation.

Read the comments on this article