Skip to main content
When you create accessible documentation, you prioritize content design that makes your documentation usable by as many people as possible regardless of how they access and interact with your documentation. Accessible documentation improves the user experience for everyone. Your content is more clear, better structured, and easier to navigate. This guide offers some best practices for creating accessible documentation, but it is not exhaustive. You should consider accessibility an ongoing process. Technologies and standards change over time, which introduce new opportunities to improve documentation.

​
What is accessibility?

Accessibility (sometimes abbreviated as a11y for the number of letters between the first and last letters of “accessibility”) is intentionally designing and building websites and tools that as many people as possible can use. People with temporary or permanent disabilities should have the same level of access to digital technologies. And designing for accessibility 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.

​
Getting started with accessibility

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.

​
First steps

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.

​
Plan your accessibility work

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.

​
Structure your content

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.

​
Use proper heading hierarchy

Each page should have a single H1 heading, which is defined by 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)

​
Write descriptive link text

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  -->
[Learn more](/organize/navigation).

​
Keep content scannable

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

​
Use proper table structure

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 |
| ------- | ------ |
| Search  | Active |
| Analytics | Active |

​
Write descriptive alt text

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 the image is included. Even with alt text, you should not rely on images alone to convey information. Make sure your content describes what the image communicates.

​
Write effective alt text

  • 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 will already know that the alt text is associated with 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)

​
Add alt text to images

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."
/>

​
Add titles to embedded content

Iframes and video embeds require descriptive titles: 
<iframe
  src="https://www.youtube.com/embed/example"
  title="Tutorial: Setting up your first documentation site"
></iframe>

​
Design for readability

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

​
Ensure sufficient color contrast

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.

​
Don’t rely on color alone

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.”

​
Use clear, concise language

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

​
Make code examples accessible

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.

​
Specify the programming language

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 context around code

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.

​
Video and multimedia accessibility

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

​
Add captions to videos

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.

​
Provide transcripts

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.

​
Consider alternatives to video-only content

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.

​
Test your documentation

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

​
Check for accessibility issues with mint a11y

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
  • Improper heading hierarchy
  • Insufficient color contrast
When the scan completes, review the reported issues and fix them in your content. Run the command again to verify your fixes.

​
Basic keyboard navigation test

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.

​
Go deeper with accessibility testing

For more comprehensive testing:

​
Additional resources

Continue learning about accessibility with these trusted resources:
⌘I