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.
Annie Streater 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.
# 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.
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, 👩🏽💻 might appear to someone as a sequence of emoji like 👨💻🟫♀️ .
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.
.github/workflows.readme-checker.yml.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
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!
To learn more about accessibility at GitHub, go to accessibility.github.com.
It’s the 10th anniversary of our global developer event! Celebrate with us by picking up in-person tickets today. It’s bound to be our best one yet.
As we’re opening up the doors to our final class of this programmatic year, we’re also looking back at our recent graduates and the partners that helped make them a success.
Game Bytes is our monthly series taking a peek at the world of gamedev on GitHub—featuring game engine updates, game jam details, open source games, mods, maps, and more. Game on!
