markdown linting accessibility style-guide documentation

Markdown Linting Guide: 15 Common Problems and How to Fix Them

Find and fix common Markdown problems including skipped headings, missing image alt text, bare URLs, broken code fences, inconsistent lists, and malformed tables.

W
WordToMD Team
·

Markdown is permissive. A document with structural mistakes may still render, which makes those mistakes easy to miss until a table breaks, a heading disappears from navigation, or an image becomes meaningless to a screen-reader user.

Markdown linting is the process of checking source text for structural, accessibility, and consistency problems before publication. Start with the Markdown Linter to catch skipped heading levels, missing image alt text, bare URLs, unlabeled or unclosed code fences, and trailing whitespace. Then use the manual checklist in this guide for broader editorial review.

Linting is not about enforcing arbitrary preferences. A useful rule should prevent a real reading, rendering, maintenance, or accessibility problem.

Quick Pre-Publish Checklist

CheckWhy it mattersAutomated or manual?
Heading hierarchyPreserves document structureLinter
Image alt textMakes images understandable without sightLinter
Descriptive linksImproves accessibility and scanningLinter + manual review
Closed code fencesPrevents the rest of the page becoming codeLinter
Code language labelsEnables useful syntax highlightingLinter
Trailing whitespaceAvoids invisible, dialect-specific behaviorLinter
One clear page titleKeeps page purpose unambiguousManual review
Consistent listsPrevents broken nestingManual review
Valid tablesKeeps column structure intactManual review
Unique headingsPrevents duplicate anchor confusionManual review
Portable HTML usageAvoids renderer-specific failuresManual review
Readable paragraphsImproves comprehensionManual review

Paste a representative document into the linter, run the checks, fix the reported lines, and then preview the complete page in its actual publishing system.

1. Skipped Heading Levels

Problem

# Deployment Guide

### Configure credentials

The document jumps from H1 to H3. It may look acceptable when font sizes are the only visible signal, but the structural outline is missing a level.

Fix

# Deployment Guide

## Configure credentials

Use headings to describe hierarchy, not to choose a visual size. If “Configure credentials” truly belongs inside a missing section, add that section:

# Deployment Guide

## Preparation

### Configure credentials

The Markdown Linter reports a heading that jumps by more than one level.

2. Multiple or Missing H1 Headings

A page should normally have one clear title. Some documentation systems generate the H1 from front matter, while others expect it in the Markdown body. Know which convention your site uses.

Ambiguous source

# Installation

# Configuration

Clear source

# Product setup

## Installation

## Configuration

If your site template renders title: Product setup as the page H1, the body may begin with H2 instead. The rule is not “every Markdown file must contain exactly one #.” The rule is “the rendered page needs one unambiguous primary heading.”

3. Headings Used Only for Emphasis

This source creates an unnecessary outline entry:

#### Important!

If the text does not introduce a section, use prose or an appropriate callout:

**Important:** Back up the database before continuing.

Headings should help readers navigate. Decorative headings make the table of contents noisy and reduce the usefulness of assistive navigation.

4. Images Without Alternative Text

Problem

![](architecture.png)

The image has no text alternative. A reader who cannot see it receives no explanation, and someone browsing broken or disabled images cannot determine its purpose.

Fix

![Request flow from the browser through the API gateway to the orders service](architecture.png)

Describe the information the image contributes, not its appearance alone. Avoid phrases such as “image of” unless the medium is important.

Decorative images are a special case. Empty alt text can be correct in HTML when an image conveys no information, but Markdown renderers and content workflows differ. If an image is purely decorative, first ask whether it belongs in technical documentation at all.

The linter flags Markdown images with empty alt text. The Image Formatter can generate image markup with an explicit alternative and optional caption.

Problem

Visit https://example.com/docs/setup for more information.

Bare URLs are hard to scan and can be unpleasant when read aloud. Generic link text is not much better:

[Click here](https://example.com/docs/setup).

Fix

Read the [service setup guide](https://example.com/docs/setup).

Descriptive links tell readers what they will open. They also remain meaningful when extracted into a list of links.

The linter identifies many bare http:// and https:// URLs, but editorial review is still required to judge whether the link text is useful.

6. Unclosed Code Fences

Problem

```javascript
const status = 'ready';

## Next section

Without a closing fence, the renderer may treat the rest of the page as code.

Fix

```javascript
const status = 'ready';
```

## Next section

An unclosed fence can break a large section of an otherwise valid document. The linter reports the line where the unmatched fence begins.

7. Code Fences Without Language Identifiers

Less useful

```
npm run build
```

Better

```bash
npm run build
```

A language identifier enables syntax highlighting and communicates what kind of content the reader is seeing. Use common identifiers such as javascript, typescript, json, html, css, bash, powershell, yaml, or markdown.

Do not add an inaccurate language merely to get colors. For unstructured output, use text when the destination recognizes it.

8. Inconsistent List Indentation

Problem

- Install dependencies
    - Production packages
  * Development packages
	- Optional tools

Mixed tabs, spaces, and markers are difficult to review and may render at different levels.

Fix

- Install dependencies
  - Production packages
  - Development packages
  - Optional tools

Choose a consistent indentation width for the project. The exact number of spaces can depend on the Markdown dialect and list content, but consistency is essential.

Use the Nested List Formatter to normalize mixed bullets, numbering, tabs, and indentation before final review.

9. Manually Typed Number Sequences

Long numbered lists are expensive to maintain:

1. Download the package.
2. Verify the checksum.
3. Install the package.
4. Restart the service.

Many Markdown renderers allow every item to use 1. while still displaying an ordered sequence:

1. Download the package.
1. Verify the checksum.
1. Install the package.
1. Restart the service.

This reduces renumbering noise in source diffs. However, explicitly numbered source is easier to discuss when instructions refer to “step 3.” Choose one project convention and apply it consistently.

Do not combine typed numbers, ordered-list markers, and paragraph text. Confirm the rendered result after editing nested steps.

10. Malformed Tables

Problem

| Name | Status | Owner |
| --- | --- |
| Search | Ready | Maya |
| Billing | Review |

The separator and data rows do not contain the same logical number of columns.

Fix

| Name | Status | Owner |
| --- | --- | --- |
| Search | Ready | Maya |
| Billing | Review | Unassigned |

Also check for unescaped pipe characters inside cells:

| Command | Description |
| --- | --- |
| `test \| deploy` | Run the matching stage |

The Markdown Table Formatter helps expose uneven rows and produces aligned source. For creating a new table visually, use the Markdown Table Generator.

11. Duplicate Headings and Anchor Collisions

A document can legitimately repeat a visible heading such as “Examples,” but automatically generated anchor IDs may become #examples, #examples-1, and #examples-2. The exact rule varies by renderer.

Repeated headings make manual links fragile:

- [API examples](#examples)
- [CLI examples](#examples)

Prefer descriptive headings:

## API examples

## CLI examples

Then generate a table of contents with the Markdown TOC Generator and verify the anchors in the target platform.

12. Trailing Whitespace

Spaces at the end of a line are invisible. In some Markdown dialects, two trailing spaces create a hard line break, which means an accidental editor action can change rendering.

The linter reports trailing whitespace so you can decide whether it is deliberate. Prefer an empty line for paragraph separation. If a hard line break is genuinely required, document and apply the project’s chosen convention consistently.

Editors can usually remove trailing whitespace automatically on save, but check that this does not change intentional line breaks in legacy content.

13. Raw HTML That Reduces Portability

Markdown often permits embedded HTML:

<div class="warning-panel">
  Restarting the service ends active sessions.
</div>

That block may work on one website and be escaped, sanitized, or styled incorrectly elsewhere. Prefer portable Markdown when it can express the same meaning:

> **Warning:** Restarting the service ends active sessions.

Use HTML deliberately for features Markdown cannot express, such as controlled image sizing or a supported <details> block. Keep a list of the destinations where the content must render and test each one.

The Callout Generator can produce platform-specific syntax for GitHub, Obsidian, and MkDocs when portability is less important than native presentation.

14. Overlong Paragraphs and Poor Scannability

Markdown can be structurally valid and still difficult to read. A wall of text containing several decisions, warnings, and procedures should be reorganized.

Use:

  • short paragraphs for one main idea;
  • descriptive headings for navigation;
  • lists for parallel items;
  • tables for genuinely comparable fields;
  • code blocks for literal input and output;
  • callouts for a small number of important exceptions.

Do not turn every sentence into a bullet. Lists work best when the items have the same grammatical and conceptual role.

Use Word Count & Reading Time to inspect paragraph count, heading count, and reading length, but treat the statistics as signals rather than targets.

15. Renderer-Specific Syntax Without a Compatibility Plan

GitHub task lists, Obsidian wiki links, MkDocs admonitions, footnotes, definition lists, and front matter are all useful, but they are not supported identically everywhere.

For example:

> [!NOTE]
> This callout is useful in destinations that recognize the syntax.

Before adopting an extension, answer three questions:

  1. Which renderer owns the final output?
  2. Does the content need to move elsewhere later?
  3. What will readers see when the extension is unsupported?

Keep a portable Markdown foundation and add platform syntax at the publishing edge when possible.

A Practical Linting Workflow

Step 1: Check the structure

Paste the source into the Markdown Linter. Fix errors first, then warnings, then informational consistency items. Automated checks should identify locations; they should not silently rewrite meaning.

Step 2: Normalize difficult elements

Use focused tools for mechanical cleanup:

Focused changes produce smaller, easier-to-review diffs than a broad formatter that rewrites the entire file.

Step 3: Preview the document

Open the source in the Markdown Editor and compare the Markdown with the rendered output. Check:

  • headings and table of contents;
  • lists and task lists;
  • tables on a narrow screen;
  • images and links;
  • code blocks and inline code;
  • callouts or raw HTML.

Step 4: Test the real destination

A generic preview cannot reproduce every renderer. Open the file in GitHub, Obsidian, GitLab, MkDocs, or the actual documentation site before publishing.

Step 5: Review meaning, not just syntax

No linter can determine whether a procedure is safe, a link points to the intended policy, or an image description communicates the important conclusion. A human reviewer should confirm accuracy, completeness, tone, and audience fit.

Team Style Guide Recommendations

A short documented convention is more effective than dozens of unspoken preferences. Define:

  • whether the page title lives in front matter or the Markdown body;
  • the permitted heading progression;
  • list indentation and ordered-list style;
  • code-fence language requirements;
  • how images and alt text are reviewed;
  • table complexity limits;
  • allowed HTML and platform extensions;
  • maximum line length, if the team uses one;
  • how links are checked;
  • which linter rules block publication.

Start with rules that prevent real defects. Add a rule only when the team understands the problem it solves.

FAQ

Is valid Markdown automatically accessible?

No. Valid syntax can still contain empty alt text, vague links, confusing headings, inaccessible diagrams, and poor reading order. Accessibility requires structural and editorial review.

Will the Markdown Linter rewrite my document?

The WordToMD linter reports line-numbered issues. It does not silently rewrite the source, so you retain control over each correction.

Why does the linter report a bare URL?

Descriptive link text is easier to scan and more useful to assistive technology. Replace the URL with a meaningful label unless the literal address is the information readers need.

Is an unlabeled code fence always wrong?

Not always, but a correct language identifier usually improves clarity and syntax highlighting. Use text for plain output when supported instead of assigning an inaccurate programming language.

Should all projects use the same linting rules?

No. A GitHub README, an Obsidian vault, an API reference, and a publishing site have different conventions. Share a core set of structural and accessibility rules, then add destination-specific checks.

Can linting replace proofreading?

No. A linter detects patterns. It cannot reliably verify technical truth, argument quality, user intent, or whether a sentence is understandable in context.

Conclusion

Good Markdown is more than source that happens to render. It has a clear outline, meaningful links, accessible images, complete code fences, consistent lists, valid tables, and a defined relationship with its publishing platform.

Run the Markdown Linter for fast structural checks, use the Markdown Editor for visual review, and apply focused formatters only where they make the source easier to maintain. The result is Markdown that is more portable, accessible, and dependable in future edits.