Writing Accessible Markdown

By the end of this lesson you'll write Markdown that everyone can use — a logical heading outline, descriptive links, meaningful image alt text, proper table headers, and structure that screen readers can convey faithfully.

Learn Writing Accessible Markdown in our free Markdown course — an interactive lesson with worked examples, a practice exercise and a quick reference.

Part of the free Markdown course at LearnCodingFast — hands-on lessons with examples you run in your browser, plus practice exercises and a quick quiz.

Accessible Markdown is like reading a document aloud to a friend over the phone . Your friend can't see the page, so "click here " or "look at this " tells them nothing — you'd naturally say "visit the download page ". You'd describe a chart instead of saying "nice picture", and you'd read section titles in order so they can follow along. A screen reader is that listener; writing with structure and descriptive words means it can pass on everything a sighted reader sees.

1. A Logical Heading Hierarchy

Headings aren't just big text — they form the outline screen reader users navigate by, jumping from heading to heading. Two rules keep that outline meaningful: use exactly one H1 as the page's single title, and don't skip levels . Go # then ## then ### in order; jumping from an H2 straight to an H4 leaves a gap that breaks the structure.

A screen reader can jump between these levels to scan the page.

Fill in the blanks with the right number of # characters so the program prints one H1, then an H2, then an H3 — no skipped levels.

2. Descriptive Link Text

Many screen reader users pull up a list of all links on a page to navigate. If every link says "click here" or "this", that list is useless. Make link text describe its destination so it stands on its own: [setup steps](setup.md) , not "for the setup steps, click here". Good link text helps everyone — it's also clearer for sighted readers scanning the page.

3. Image Alt Text

Every meaningful image needs alt text — the text in  — that conveys what the image shows to someone who can't see it. Describe the meaning , not the file: "Bar chart: sales doubled from Q1 to Q2" beats "chart.png". For purely decorative images (dividers, spacers) use empty alt  so screen readers skip them rather than announcing a useless filename.

✓ "Image: Bar chart: sales doubled from Q1 to Q2"

✓ (decorative image, with empty alt) — skipped silently

A missing alt would make some readers announce the filename instead, which is just noise.

Here's a worked example that prints accessible Markdown source . Run it, read each printed line, then notice how the structure, one H1, ordered levels, descriptive links, and real alt text, is what makes it usable for everyone.

Fill in the blanks so the program prints a link with descriptive text and an image with meaningful alt text . Avoid "click here" and avoid empty alt for a meaningful image.

4. Table Headers and Honest Formatting

Give every table a clear header row so assistive tech can associate each data cell with its column — it can announce "Capital: Paris" rather than a lone "Paris". And never rely on formatting alone to carry meaning: if "items in bold are required", a user who can't perceive the bold misses it entirely. State the meaning in words (mark required items with the word "required") so it survives without the styling.

Each cell is announced with its column name, e.g. "Capital: Paris".

No blanks this time — just a brief and an outline. Use console.log to print the source for a short page with one H1, ordered H2/H3 sections, a descriptive link, a meaningful image with alt text, and a small table with a header row.

Q: Does Markdown become accessible automatically?

Markdown produces real HTML headings, lists, and links, which is a great start. But meaning depends on you: descriptive link text, alt text, header rows, and a correct heading order.

Only when the image is purely decorative and conveys no information. Empty alt tells screen readers to skip it; a meaningful image always needs descriptive alt.

Q: Is it really a problem to skip a heading level?

Yes. Users who navigate by headings rely on the order; a gap (H2 to H4) breaks the outline and makes the structure confusing.

Use emphasis for visual weight, but also make the meaning explicit in words, so it isn't lost for anyone who can't perceive the styling.

Where to go next: revisit the course overview to review earlier lessons, then apply these habits to a real README or docs site. Congratulations on completing the Markdown course! 📝

Practice quiz

• Browse all free courses
• Cheat sheets & quizzes
• Coding dictionary