Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.mintlify.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

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 experience for everyone. Your content is clearer, better structured, and easier to navigate—whether users access it with a screen reader, keyboard navigation, mobile device, or slow network connections. 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.

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

​
Get 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 link text and destination -->
[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 | Last updated |
| ------- | ------ | ------------ |
| 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.

​
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.
Learn more about working with images in the media guide.

​
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 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. 
{
  "colors": {
    "primary": "#0066CC",
    "background": {
      "light": "#FFFFFF",
      "dark": "#1A1A1A"
    }
  }
}
In the poor example, yellow (#FFCC00) on white has insufficient contrast. The dark mode background (#333333) is too light for optimal readability.

​
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.
See the style and tone guide for more writing best practices.

​
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 and videos.
  • Insufficient color contrast.

​
Interpret the output

When the scan completes, you’ll see a report like this: 
Accessibility Issues Found:

❌ Missing alt text (3 issues)
  - /guides/quickstart.mdx:45 - Image missing alt text
  - /api-reference/users.mdx:12 - Image missing alt text
  - /guides/setup.mdx:89 - Video missing title attribute

⚠️  Color contrast (2 issues)
  - Primary color (#FFCC00) on light background fails WCAG AA (2.1:1)
  - Link color (#FF6B6B) on dark background fails WCAG AA (3.2:1)

✅ 0 issues found in 15 other pages

​
Fix common issues

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.

​
Use flags for targeted checks

Use flags to check for specific accessibility issues: 
# Check only for missing alt text
mint a11y --skip-contrast

# Check only for color contrast issues
mint a11y --skip-alt-text

# Fail CI/CD pipeline if issues are found
mint a11y --fail-on-error

​
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:

​
Frequently asked questions

Most organizations aim for WCAG 2.1 Level AA compliance, which is the standard for many legal requirements and provides a good balance of accessibility and feasibility. Level AAA is more stringent and may not be achievable for all content types.Start with Level AA as your baseline. The mint a11y command checks for common Level AA requirements like color contrast and alt text.
On Mac, use the built-in VoiceOver (press Cmd + F5 to enable). On Windows, download NVDA (free and open source). Navigate through your documentation using only the screen reader and listen for proper heading announcements, descriptive link text, alt text on images, and logical reading order. You don’t need to be an expert to catch major issues.
Alt text is read by screen readers and appears when images fail to load. It describes what the image shows and why it’s relevant. Alt text is required for accessibility.Captions appear below images for all users. They provide additional context, attribution, or explanation. Captions are optional and supplement alt text.Use both when an image needs description (alt text) and additional context (caption).
Yes, but sparingly. Screen readers announce emoji names out loud, so multiple emojis in a row become disruptive. For example, 🎉 becomes “party popper” and 🚀 becomes “rocket” so 🎉 🚀 becomes “party popper rocket”. Avoid using emojis to convey critical information. If the emoji were removed, the meaning should still be clear. When in doubt, use text instead.
Specify the language on every code block for syntax highlighting. Provide context before and after code blocks so screen reader users understand what the code does—screen readers often skim code itself. Break long examples into smaller chunks and use descriptive variable names that make sense when read aloud.
Prioritize by impact. Fix missing alt text, broken keyboard navigation, and insufficient color contrast first—these affect the most users. Poor heading hierarchy and vague link text come next. Document known issues with a plan to address them. Progress is better than perfection.

​
Additional resources

Continue learning about accessibility with these trusted resources:

Related topics

AI-native documentationQuickstartAnalyze your documentation