Your GitHub profile README is a front door—make sure it opens for everyone

The README on your GitHub profile is often the first thing people see when they visit your page. It’s a snapshot of your work, skills, and professional identity, so it’s worth making sure everyone can actually read and understand it. Accessibility here means designing content so that people with disabilities can navigate and interact with it just as easily as anyone else.

Accessible READMEs build trust, improve usability for all visitors, show a commitment to inclusivity, and set a good precedent for every other .md file you write. The good news is that you can make meaningful improvements without writing a single line of code—just by reviewing how you handle links, images, headings, language, lists, and emoji.

Assistive technology often presents links in isolation—as a list, or by reading out each link’s name. If your link text says click here or this, users have no way to tell where each link leads without extra context.

  • Make link text specific, such as blog post about accessibility, instead of generic text.
  • Avoid repeating the same link text for different destinations.
  • Include context about where the link goes.

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

Describe images with alt text

Alt text ensures that people using screenreaders—often those with low vision—can still grasp what an image conveys. Think of alt text like a tweet: concise, descriptive, and meaningful.

  • Include any text that appears inside the image.
  • Consider context: why is the image there, and what does it communicate?
  • Skip phrases like “image of” or “photo of,” since screenreaders already announce the presence of an image. Do include descriptors like “screenshot of,” because that context matters.
  • If a longer description is needed, put it in a <details> tag or link to external material.

The right alt text depends on the image type: a chart or infographic might summarize the key data, a photo of you might describe your appearance or surroundings, and a project screenshot might outline the most important product features.

In Markdown, add alt text inside the square brackets of the image syntax:

![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))

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!'

Use heading structure deliberately

Headings give your content structure. Screenreader users rely on them to understand the layout and jump directly to sections; visual readers—including some with ADHD or dyslexia—benefit from scannable, hierarchical text.

Markdown uses # for headings. Use one # for the page title, then ##, ###, and so on for subsections. Think of a newspaper front page: the most important heading sits at the top, with smaller headings underneath.

# 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)

Don’t skip levels (for example, going from ## to ####). Skipping levels can confuse navigation and make screenreader users wonder if they missed a section.

Structure lists properly and keep language plain

Lists need correct markup to be recognized as lists. Using special characters or emoji as bullet-point decorations will cause screenreaders to read the content as ordinary paragraph text, which can change its meaning. Proper list structure also provides useful context—for instance, a screenreader might announce “Apples, one of three” for the first item in a three-item list.

Use the standard Markdown list markers (*, -) for each item.

For readability, free tools like Hemingway, Grammarly, and Alex can help you simplify and clarify your writing. Many have web versions, so you can copy and paste sections of your README and check their readability without installing anything.

Use emoji thoughtfully

Emoji add personality, but they add noise too. Screenreaders read out each emoji’s full name—like “face with stuck-out tongue and squinting eyes”—so stringing several together can be jarring. Excessive emoji can also be distracting for some neurodivergent people, including autistic users.

Not all browsers and devices render every emoji, particularly variations based on skintone or gender. An emoji like 👩🏽‍💻 (woman with medium skintone with a laptop) might show up for someone else as a sequence such as 👨💻🟫♀️ (default-yellow man with laptop, brown square, and female symbol).

Automate accessibility checks

Several tools can surface accessibility problems in your README and other Markdown files with minimal effort.

Browser and editor extensions

GitHub Actions

Run accessibility tests automatically every time you change a Markdown file:

  1. Create a directory named .github/workflows in your repository.
  2. Add a YAML file named 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

  1. Commit and merge to your main branch.
  2. Check the Actions tab to see results.

Built-in browser tools

  • Use your browser’s developer tools to verify 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 it.

Encourage others to follow

Once you’ve applied these changes, you can spread the word by adding the Markdown snippet below to your README. It links back to this post and invites other GitHub users to make their profiles accessible too.

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)".

For questions and community discussion, join the GitHub Community discussion about making your profile accessible. For more on accessibility at GitHub, visit accessibility.github.com.