Build what's next on GitHub, the place for anyone from anywhere to build anything.
Join us October 28-29 in San Francisco or online for GitHub Universe, our flagship developer event uniting people, agents, and the world's code.
Your profile’s README invites the world to know you and your work, so it’s important that everyone can read and understand it. In this post, we share some tips for making your README more 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.
By making the README on your GitHub profile accessible, you:
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:
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.
blogpost about accessibility, instead of using generic text like this or here.Read my blog post about crafting an inclusive and accessible resumé here.
Read my blog post, “Crafting an inclusive and accessible resumé,” on GitHub Community.
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.
<details> tag or link to an external resource.Alt text should help users understand the meaning or intent of the image, which will be different depending what type of image it is.
In Markdown, add alt text by putting the image description inside the square brackets:
)
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.
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.
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.
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.
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).
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.
You can use GitHub Actions to run tests on your content every time you take an action on a Markdown file.
Create a directory in your repository with the name .github/workflows.
Create a YAML file with the name readme-checker.yml.
Paste the code from the markdownlint example YAML file:
Commit and merge to your main branch.
Go to the Actions tab of your repository and see the results!
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.
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!
To learn more about accessibility at GitHub, go to accessibility.github.com.