How to create accessible documentation

Create accessible documentation following WCAG guidelines with semantic HTML, keyboard navigation, alt text, and inclusive content practices.

Design accessible documentation so as many people as possible can use it, regardless of how they access and interact with it.

Accessible documentation improves the experience for everyone. Your content is clearer, better structured, and easier to navigate. This applies whether users access it with a screen reader, keyboard navigation, mobile device, or slow network connection.

This guide covers best practices for accessible documentation. Accessibility is an ongoing process. Technologies and standards evolve, and there are always opportunities to improve. Start with high-impact changes and build accessibility into your workflow.

Accessibility is the practice of designing and building websites and tools that as many people as possible can use. The term is sometimes abbreviated as a11y, using the 11 letters between the first and last letters of "accessibility." People with temporary or permanent disabilities should have the same level of access to digital technologies. Accessibility also benefits everyone, including people who access your website on mobile devices or slow networks.

Accessible documentation follows web accessibility standards, primarily the Web Content Accessibility Guidelines (WCAG). These guidelines help ensure your content is perceivable, operable, understandable, and robust.

Making your documentation accessible is a process. You don't have to fix everything all at once and you can't do it only once.

If you're just beginning to implement accessibility practices for your documentation, consider a phased approach where you start with high-impact changes and build from there.

Here are three things you can do right now to improve the accessibility of your documentation:

1. Run mint a11y to identify accessibility issues in your content.
2. Add alt text to all images.
3. Check your heading hierarchy to ensure one H1 per page and headings follow sequential order.

The best workflow is the one that works for your team. Here is one way that you can approach accessibility work:

Phase 1: Images and structure

• Review all images for descriptive alt text.
• Audit link text and replace generic phrases like "click here."
• Fix heading hierarchy issues across your documentation.

Phase 2: Navigation and media

• Test keyboard navigation on your documentation.
• Test screen reader support.
• Add captions and transcripts to embedded videos.
• Review color contrast.

Phase 3: Build it into your workflow

• Run mint a11y before publishing new content.
• Include accessibility checks in your content review process.
• Test keyboard navigation when adding interactive features.
• Verify new external links and embeds include proper titles and descriptions.

Starting small and building accessibility into your regular workflow makes it sustainable. Each improvement helps more users access your documentation successfully.

Well-structured content is easier to navigate and understand, especially for screen reader users who rely on headings to move through pages and people who use keyboard navigation.

Each page should have a single H1 heading, which comes from the title: property in a page's frontmatter. Use additional headings in order without skipping. For example, don't skip from H2 to H4.

<!-- Good -->
# Page title (H1)

## Main section (H2)

### Subsection (H3)

### Another subsection (H3)

## Another main section (H2)

<!-- Bad -->
# Page title (H1)

## Main section (H2)

#### Subsection (H4)

### Another subsection (H3)

Headings at the same level should have unique names.

<!-- Good -->
## Accessibility tips (H2)

### Write effective alt text (H3)

### Use proper color contrast (H3)

<!-- Bad -->
## Accessibility tips (H2)

### Tip (H3)

### Tip (H3)

Link text should be meaningful and connected to the destination. Avoid vague phrases like "click here" or "read more."

<!-- Good -->
Learn how to [configure your navigation](/organize/navigation).

<!-- Unclear relation between link text and destination -->
[Learn more](/organize/navigation).

• Break up long paragraphs.
• Use lists for steps and options.
• Highlight information with callouts.

Use tables sparingly and only for tabular data that has meaning inherited from the column and row headers.

When using tables, include headers so screen readers can associate data with the correct column:

| Feature | Status | Last updated |
| ------- | ------ | ------------ |
| Search  | Active | 2024-03-15   |
| Analytics | Active | 2024-03-10 |
| Exports | Beta | 2024-03-20 |

| Search | Active | 2024-03-15 |
| Analytics | Active | 2024-03-10 |
| Exports | Beta | 2024-03-20 |

The poor example lacks headers, making it impossible for screen readers to announce what each column represents.

Alt text makes images accessible to screen reader users and appears when images fail to load. Images in your documentation should have alt text that describes the image and makes it clear why you included the image. Even with alt text, you should not rely on images alone to convey information. Make sure your content describes what the image communicates.

• Be specific: Describe what the image shows, not just that it's an image.
• Be concise: Aim for one to two sentences.
• Avoid redundancy: Don't start with "Image of" because screen readers already know that the alt text belongs to an image. However, you should include descriptions like "Screenshot of" or "Diagram of" if that context is important to the image.

<!-- Good -->
![Screenshot of the dashboard showing three active projects and two pending invitations](/images/dashboard.png)

<!-- Not helpful -->
![Dashboard screenshot](/images/dashboard.png)

For Markdown images, include alt text in the square brackets:

![Description of the image](/path/to/image.png)

For HTML images, use the alt attribute:

<img
  src="/images/screenshot.png"
  alt="Settings panel with accessibility options enabled. The options are emphasized with an orange rectangle."
/>

Iframes and video embeds require descriptive titles:

<iframe
  src="https://www.youtube.com/embed/example"
  title="Tutorial: Setting up your first documentation site"
></iframe>

Visual design choices affect how accessible your documentation is to users with low vision, color blindness, or other visual disabilities.

If you customize your theme colors, verify the contrast ratios meet WCAG requirements:

• Body text: minimum 4.5:1 contrast ratio
• Large text: minimum 3:1 contrast ratio
• Interactive elements: minimum 3:1 contrast ratio

Test both light and dark mode. The mint a11y command checks for color contrast.

{
  "colors": {
    "primary": "#0066CC",
    "background": {
      "light": "#FFFFFF",
      "dark": "#1A1A1A"
    }
  }
}

{
  "colors": {
    "primary": "#FFCC00",
    "background": {
      "light": "#FFFFFF",
      "dark": "#333333"
    }
  }
}

In the poor example, yellow (#FFCC00) on white has insufficient contrast. The dark mode background (#333333) is too light for optimal readability.

If you use color to convey information, include a text label or icon as well. For example, don't mark errors only with red text. Include an error icon or the word "Error."

• Write in plain language.
• Define technical terms when first used.
• Avoid run-on sentences.
• Use active voice.

Code blocks are a core part of technical documentation, but they require specific accessibility considerations to ensure screen reader users can understand them. In general, follow these guidelines:

• Break long code examples into smaller, logical chunks.
• Comment complex logic within the code.
• Consider providing a text description for complex algorithms.
• When showing file structure, use actual code blocks with language labels rather than ASCII art.

Always declare the language for syntax highlighting. This helps screen readers announce the code context to users:

```javascript
function getUserData(id) {
  return fetch(`/api/users/${id}`);
}
```

Provide clear context for code blocks:

The following function fetches user data from the API:

```javascript
function getUserData(id) {
  return fetch(`/api/users/${id}`);
}
```

This returns a promise that resolves to the user object.

Videos, animations, and other multimedia content need text alternatives so all users can access the information they contain.

Captions make video content accessible to users who are deaf or hard of hearing. They also help users in sound-sensitive environments and non-native speakers:

• Use captions for all spoken content in videos.
• Include relevant sound effects in captions.
• Ensure captions are synchronized with the audio.
• Use proper punctuation and speaker identification when multiple people speak.

Most video hosting platforms support adding captions. Upload caption files or use auto-generated captions as a starting point, then review for accuracy.

Transcripts offer an alternative way to access video content. They're searchable, easier to reference, and accessible to screen readers:

<iframe
  src="https://www.youtube.com/embed/example"
  title="Tutorial: Setting up authentication"
></iframe>

<Accordion title="Video transcript">
In this tutorial, we'll walk through setting up authentication...
</Accordion>

Place transcripts near the video or provide a clear link to access them.

If critical information only appears in a video:

• Provide the same information in text form.
• Include key screenshots with descriptive alt text.
• Create a written tutorial that covers the same material.

This ensures users who can't access video content can still complete their task.

Regular testing helps you catch accessibility issues before users encounter them.

Use the mint a11y CLI command to automatically scan your documentation for common accessibility issues:

mint a11y

The command checks for:

• Missing alt text on images and videos.
• Insufficient color contrast.

For flags that limit the scan to one type of check, see the mint a11y reference.

Missing alt text: Add descriptive alt text to the image or video:

<!-- Before -->
![](/images/dashboard.png)

<!-- After -->
![Dashboard showing three active projects and two pending invitations](/images/dashboard.png)

Color contrast failures: Update your theme colors in docs.json:

{
  "colors": {
    "primary": "#0066CC",  // Changed from #FFCC00
    "light": "#3399FF",
    "dark": "#004C99"
  }
}

Run mint a11y again to verify your fixes.

Navigate through your documentation using only your keyboard:

1. Press Tab to move forward through interactive elements.
2. Press Shift + Tab to move backward.
3. Press Enter to activate links and buttons.
4. Verify all interactive elements are reachable and have visible focus indicators.

For more comprehensive testing:

• Screen readers: Test with NVDA (Windows) or VoiceOver (Mac).
• Browser extensions: Install axe DevTools or WAVE to scan pages for issues.
• WCAG guidelines: Review the Web Content Accessibility Guidelines for detailed standards.

Continue learning about accessibility with these trusted resources:

• WebAIM: Practical articles and tutorials on web accessibility
• The A11y Project: Community-driven accessibility resources and checklist
• W3C Web Accessibility Initiative (WAI): Official accessibility standards and guidance

• Guides
• Quickstart
• Update