Markdown Standards

Apply these standards when creating or editing Markdown documentation.

Content Rules

1. Headings

• Use appropriate heading levels (H2, H3, etc.) to structure content

• Do NOT use H1 - it will be generated from the title/front matter

• Use headings hierarchically (don't skip levels)

• Recommend restructuring if H4+ headings are needed

Good:

Main Section

Subsection

Detail (use sparingly)

Bad:

Title (don't use H1)

Subsection (skipped H2)

2. Lists

• Use - for bullet points

• Use 1. for numbered lists

• Indent nested lists with two spaces

• Ensure proper spacing between list items

Example:

• First item
• Second item
  • Nested item
  • Another nested item
• Third item

1. First step

2. Second step

3. Third step

4. Code Blocks

• Use fenced code blocks with triple backticks

• Always specify the language for syntax highlighting

• Use inline code with single backticks for short snippets

Example:

const greeting = 'Hello, World!'
console.log(greeting)

Use const for immutable variables.

4. Links

• Use descriptive link text

• Ensure URLs are valid and accessible

• Prefer relative links for internal documentation

Good:

See the installation guide for details.

Bad:

Click here.

5. Images

• Include descriptive alt text for accessibility

• Use relative paths for local images

• Optimize image sizes

Example:

6. Tables

• Use proper markdown table syntax

• Ensure proper alignment

• Include headers

Example:

Formatting and Structure

Line Length

• Limit line length to 80-100 characters for readability

• Maximum 400 characters per line

• Use soft line breaks for long paragraphs

Whitespace

• Use blank lines to separate sections

• Add blank line before and after code blocks

• Add blank line before and after lists

• Avoid excessive whitespace

Front Matter

Include YAML front matter at the beginning of the file:

title: Document Title description: Brief description of the document author: Author Name date: 2026-01-29 tags: [tag1, tag2]

Content Quality

Clarity

• Write clear, concise sentences

• Use active voice

• Avoid jargon unless necessary

• Define technical terms

Structure

• Start with a brief introduction

• Use headings to organize content logically

• Include examples where helpful

• End with next steps or related resources

Consistency

• Use consistent terminology throughout

• Follow the same formatting patterns

• Maintain consistent heading capitalization

Examples

Good README Structure

title: Project Name description: Brief description of what the project does

Overview

Brief introduction to the project and its purpose.

Features

• Feature 1
• Feature 2
• Feature 3

Installation

npm install project-name

Usage

import { feature } from 'project-name'

feature.doSomething()

Configuration

Available configuration options:

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.

Good Documentation Page

title: API Reference description: Complete API documentation for the service

Authentication

All API requests require authentication using an API key.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.example.com/endpoint

Endpoints

GET /users

Retrieves a list of users.

Parameters:

• limit (optional): Maximum number of results (default: 10)
• offset (optional): Pagination offset (default: 0)

Response:

{
	"users": [{ "id": 1, "name": "John Doe" }],
	"total": 100
}

Example:

curl https://api.example.com/users?limit=5

Validation

Tools

• Use markdown linters (markdownlint)

• Validate links with link checkers

• Check spelling and grammar

Checklist

• ✅ No H1 headings in content

• ✅ All code blocks have language specified

• ✅ All images have alt text

• ✅ Links are valid and descriptive

• ✅ Tables are properly formatted

• ✅ Line length under 100 characters (400 max)

• ✅ Proper front matter included

• ✅ Consistent heading hierarchy

When to Apply

Apply these standards when:

• Creating README files

• Writing documentation

• Creating guides and tutorials

• Editing existing markdown files

• Creating changelog files

• Writing blog posts or articles

• User asks about markdown formatting