Markdown Best Practices

Writing Markdown is easy. Writing good Markdown — clear, consistent, and maintainable across a team — takes intention. This guide covers practical conventions that make your documents easier to read both in their raw source form and when rendered. These practices are drawn from widely-adopted style guides used in open-source projects and technical writing teams.

1. Document Structure

Start with a single H1

Every document should have exactly one top-level heading (# Title) that describes what the document is about. This becomes the page title in most renderers and is critical for accessibility and SEO.

# API Authentication Guide

## Overview

## Getting Started

Don't

## API Authentication Guide

## Overview

## Getting Started

Use heading levels sequentially

Never skip heading levels — go from H2 to H3, not H2 to H4. This creates a proper document outline and helps screen readers navigate your content.

## Installation
### Prerequisites
### Steps
## Configuration
### Environment Variables

Don't

## Installation
#### Prerequisites
#### Steps
## Configuration
#### Environment Variables

Add a brief introduction

After the title, include 1-3 sentences explaining what this document covers and who it's for. Don't make readers guess whether this is the right document for their needs.

2. Line Length and Wrapping

There are two common approaches to line wrapping in Markdown source files:

One sentence per line — Each sentence starts on a new line. This makes diffs cleaner because changing one sentence doesn't reflow the entire paragraph.
Soft wrap at 80-120 characters — Traditional approach that keeps lines readable in terminals and editors without soft-wrap.

Pick one style and use it consistently across your project. The "one sentence per line" approach is increasingly popular because it produces better git diffs — a single sentence change shows as one added and one removed line, not a full paragraph rewrite.

Tip: Git-friendly paragraphs

When writing documentation that will be reviewed in pull requests, one-sentence-per-line makes reviewers' lives significantly easier. They can comment on specific sentences without quoting entire paragraphs.

3. Consistent Formatting

Headings

Use ATX-style headings (# Heading) not Setext-style (Heading\n===)
Always include a space after the # characters
Leave one blank line before and after each heading
Don't end headings with punctuation
Use sentence case ("Getting started") or title case ("Getting Started") — but be consistent

Lists

Use - for unordered lists (most common in open-source; * is also fine but pick one)
Use 1. for all items in ordered lists — Markdown auto-numbers them, and this avoids renumbering when you insert items
Indent nested lists with 2 or 4 spaces, consistently
Add a blank line before and after a list

Steps to deploy:

1. Run the build
1. Run tests
1. Push to staging
1. Verify health checks
1. Promote to production

Don't

Steps to deploy:
1. Run the build
2. Run tests
3. Push to staging
4. Verify health checks
5. Promote to production

Emphasis

Use **bold** for important terms being introduced or critical warnings
Use *italic* for emphasis or when referencing titles of works
Use `backticks` for code, commands, file names, key names, and technical terms
Don't overuse emphasis — if everything is bold, nothing stands out

4. Links

Use descriptive link text

Link text should describe where the link goes, not just say "click here" or "this page." This helps accessibility (screen readers) and scannability.

See the [authentication guide](./auth.md)
for setup instructions.

Read the [API rate limiting docs](./rate-limits.md)
before deploying.

Don't

Click [here](./auth.md) for the auth guide.

For rate limiting info, see [this page](./rate-limits.md).

Use reference links for repeated URLs

When a URL appears multiple times or when inline links make text hard to read, use reference-style links:

This feature requires [Node.js 18+][node] and [TypeScript 5+][ts].
See the [installation guide][install] for setup details.

[node]: https://nodejs.org/
[ts]: https://www.typescriptlang.org/
[install]: ./docs/install.md

Relative vs. absolute links

Within a repository or documentation site, use relative links (./other-doc.md) so links work regardless of where the docs are hosted. Use absolute URLs only for external resources.

5. Code Blocks

Always specify the language

Even when you think the language is obvious, specifying it enables syntax highlighting and helps readers identify what they're looking at:

```bash
npm install express
```

Don't

```
npm install express
```

Keep examples runnable

Code examples should work when copy-pasted. Include necessary imports, variable declarations, and context. If an example is a fragment, indicate that clearly:

```javascript
// In your express route handler:
app.get('/api/users', async (req, res) => {
  const users = await db.users.findAll();
  res.json(users);
});
```

Use appropriate block types

Use `inline code` for short references: file names, function names, CLI commands
Use fenced blocks for multi-line code, command output, or configuration files
Use ```console or ```bash for terminal commands
Use ```text for plain output that shouldn't be highlighted

6. Images and Media

Always include meaningful alt text — describe what the image shows
Store images in a dedicated directory (e.g., docs/images/ or .github/assets/)
Use descriptive file names: auth-flow-diagram.png not screenshot1.png
Optimize image file size — compress PNGs and use SVGs for diagrams where possible
Consider using Mermaid diagrams instead of images for flowcharts and architectures — they're searchable, editable, and render at any resolution

7. Tables

Only use tables for genuinely tabular data — not for layout
Keep tables simple — if a cell needs multiple paragraphs, use a list or subsection instead
Align columns in your source for readability (not required by Markdown, but helps maintainers)
Include a header row — tables without headers render unpredictably

8. File Organization

For larger documentation projects, adopt a clear file structure:

docs/
├── README.md           # Entry point, table of contents
├── getting-started.md  # Quick start guide
├── installation.md     # Detailed setup
├── configuration.md    # Config reference
├── guides/
│   ├── authentication.md
│   ├── deployment.md
│   └── troubleshooting.md
├── api/
│   ├── overview.md
│   └── endpoints.md
└── images/
    └── architecture.png

Name files with lowercase kebab-case. Use README.md (uppercase) as the entry point in each directory since GitHub and most platforms auto-display it.

9. Whitespace and Spacing

Use one blank line between block elements (headings, paragraphs, lists, code blocks)
Don't use more than one consecutive blank line
End files with a single newline character
Don't add trailing whitespace (configure your editor to trim it)
Be consistent with indentation — 2 spaces for nested lists is most common

10. Accessibility Considerations

Alt text on images — Screen readers depend on this. Describe the content, not just "screenshot"
Descriptive links — "Click here" means nothing out of context. Use "See the deployment guide" instead
Sequential headings — Assistive technology uses heading levels for navigation
Language in code blocks — Helps screen readers announce code blocks appropriately
Don't rely on color alone — If you use colored text or emoji to indicate status, include text labels too

Preview your Markdown — Check formatting, heading structure, and rendering before publishing with MD Viewer's live preview.

Open MD Viewer