5 tips for making your GitHub profile page accessible

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 repository.
• Increase clarity and usability for everyone, not just people with disabilities.
• Demonstrate your commitment to inclusivity.
• Build good habits for all .md files.

Tips for 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

Make links descriptive

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 blog post about crafting an inclusive and accessible resumé here.

Good example:

Read my blog post, “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 with low vision 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.
• If a longer description is required in addition to the alt text, include the long description in a <details> tag or link to an external resource.
• Include any image text in 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 summarize 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 who 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.

Structure lists with proper markup

When writing lists, use the correct markup so that people who use assistive technology can read and understand the list as you intend it.

Only use correct list markup (*, -, or - in Markdown) for each list item so that the content is clearly structured for everyone. You might be tempted to use special characters or emoji as bullet points for decorative effect, but doing this means screenreaders will not be able to recognize the list as a list and will read it as normal paragraph text, which might change the meaning.

Structuring lists correctly also gives people who use a screenreader important 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.”

Read more about Markdown syntax for lists.

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.

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 repository 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 repository 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 blogpost "[Tips for Making your GitHub Profile Page Accessible](https://github.blog/2023-10-26-5-tips-for-making-your-github-profile-page-accessible)".

Have questions, want to learn from others, or have something to share? Join the GitHub Community discussion about making your profile accessible. We’d love to hear from you!

Written by

Annie Streater

@streats