The README on your GitHub profile acts like a front door to your work, skills, and professional self, so it's important that everyone who visits your profile can read and understand it. In this post we'll be sharing some tips to help you make your README more accessible. Making content accessible means designing it so that people with disabilities can navigate and interact with it just as easily and comfortably as everyone else.

Why are accessible READMEs important?

By making the README on your GitHub profile accessible, you:

• Invite trust and exploration into your repo
• Increase clarity and usability for everyone, not just people with disabilities
• Demonstrate your commitment to inclusivity
• Build good habits for all .md files

Making your README accessible

The great news is, you can make your README more accessible without needing to code! You can do this by checking the .md file for:

• Link context
• Image alt text
• Heading structure
• Plain language
• Use of emoji

Use descriptive links

Assistive technology presents links in isolation, for example by presenting a list of links or by reading out the name of each link, so it’s important that links make sense on their own. Links with ambiguous text such as “click here” can be difficult to distinguish from other links on the page that say the same thing. This leaves users without context as to what they’re clicking into.

• Make link text specific, for example "blogpost about accessibility", instead of using generic text like "this" or "here"
• Avoid multiple links with the same link text
• Include context about the link destination

Bad example:

Read my blogpost about crafting an inclusive and accessible resumé here.

Good example:

Read my blogpost, "Crafting an inclusive and accessible resumé" on GitHub Community.

Add ALT text to images

Using image descriptions (sometimes called "alt text") helps make sure that everyone can extract meaning from the images in your README file. People who use a screenreader access the image description to understand the context of the image that is displayed.

• Think of alt text like a tweet: be succinct, concise and descriptive.
• Include any image text in the the description
• Consider the context - why was this image used? What does it convey or communicate?
• You don't need to include “image of, photo of…” as that is communicated by the screenreader, but it is appropriate to include “screenshot of…” as this image context is important to convey

Alt text should help users understand the meaning or intent of the image, which will be different depending what type of image it is.

• The alt text for a chart or infographic might summarise the data (in addition to the surrounding text including details of the data)
• A photo of you might describe your physical appearance or surroundings
• A screenshot of a project might outline the most important elements of the product

In Markdown, add alt text by putting the image description inside the square brackets:

![Mona the Octocat in the style of Rosie the Riveter. Mona is wearing blue coveralls and a red and white polka dot hairscarf, on a background of a yellow circle outlined in blue. She is holding a wrench in one tentacle, and flexing her muscles. Text says "We can do it!"]([https://octodex.github.com/images/welcometocat.png](https://octodex.github.com/images/mona-the-rivetertocat.png))

Use proper heading formatting

Proper headings give structure to Markdown content. When information is structured properly, people that use assistive technology can understand the structure of the content and navigate directly to different sections. Using correct headings also helps visual users scan content more easily, including some people who may struggle with large amounts of unstructured text, such as people with ADHD or dyslexia.

Think of it like a newspaper front page, with the largest headings at the top, and smaller headings near the bottom. This presents the most important information in a weighted fashion.

Markdown uses # to create headings in a hierarchy. Use one # for the page title, then continue with the appropriate number of # for each heading level.

# Welcome to my GitHub profile

## About me
I'm Mona, an Octocat and GitHub mascot! 

### Likes
* Tuna melts
* Beautiful code
* Swimming in the ocean

## Contact me
Find me over on the [GitHub Blog](https://github.blog/) or on the [GitHub Community Discussions](https://github.com/orgs/community/discussions)

It's important not to skip heading levels (for example, ## followed by ####) as this can make reading order and navigation confusing. When headings are skipped, someone using assistive technology may wonder if they missed a heading somewhere else.

Use plain language to make your content readable

Apps like Hemingway, Grammarly and Alex can help you make your writing clearer, simpler and more inclusive. Some of these apps have web versions so you don’t need to install anything.

Copy and paste sections of your README into one of these tools to check for its readability and adjust accordingly.

Consider your use and placement of emoji

Emoji are a fun way to express yourself, but use them thoughtfully to make sure your README is enjoyable for others to read, too.

Screenreaders describe emoji by reading out their full name. Some emojis have long names, like "face with stuck-out tongue and squinting eyes", so you should avoid using several in a row, as this can be quite jarring when read out by a screenreader. Using too many emojis can also be distracting for some neurodivergent people such as autistic people.

You might be tempted to use emoji instead of bullet points in a list, but keep in mind that this means the list will not be structured as a list, making it difficult for people who use assistive technology to navigate and read. It's important to use properly marked up lists to give people that use a screenreader context about the depth of the list. For example, the first bullet point in a list of fruit might be announced by a screenreader as "Apples, one of three."

Keep in mind that some browsers and devices might not support all emoji, especially variations like skintone or gender. For example, 👩🏽‍💻 (woman with medium skintone with a laptop) might appear to someone as a sequence of emoji like 👨‍💻🟫♀️ (default yellow skintone man with a laptop followed by a brown square and the female symbol).

Using tools and automation to check your README for accessibility

Along with keeping the above tips in mind, there are lots of useful tools that make it easy to identify accessibility issues in your README and other .md files.

Browser and code editor extensions

• Axe dev tools browser extension on the Chrome store (also works in Edge)
• github-markdown-a11y-extension by @iansan5653
• markdownlint extension for VSCode

GitHub Actions workflows

You can use GitHub Actions to run tests on your content every time you take an action on a Markdown file.

1. Create a directory in your repo with the name .github/workflows
2. Create a YAML file with the name readme-checker.yml
3. Paste the code from the markdownlint example YAML file:

   on: [push, pull_request]
   
   jobs:
     lint:
       runs-on: ubuntu-latest
       steps:
       - uses: actions/checkout@v3
       - uses: DavidAnson/markdownlint-cli2-action@v11
         with:
           globs: |
             *.md
             !test/*.md
   

4. Commit and merge to your main branch
5. Go to the Actions tab of your repo and see the results!

Built-in browser tools

• Use your browser's developer tools to check your alt text is correctly implemented
• In Chrome, right-click on selected text and use "Speech" > "Start speaking" to simulate how a screenreader might announce content

Share your work to promote accessibility on GitHub

Once you've used these tips to make your README more accessible, why not spread the word? Add the Markdown below to your README to share this post and encourage other GitHub users to follow your great example.

This README has been optimized for accessibility based on GitHub's Community post "[Tips for Making your GitHub Profile Page Accessible](https://github.com/community)".

Have questions or want to share how you've made your GitHub profile more accessible? We'd love to hear from you in the comments!