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

3. 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:

```javascript
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](./docs/installation.md) for details.

Bad:

Click [here](./docs/installation.md).

5. Images

• Include descriptive alt text for accessibility
• Use relative paths for local images
• Optimize image sizes

Example:

![Project architecture diagram showing the main components](./assets/architecture.png)

6. Tables

• Use proper markdown table syntax
• Ensure proper alignment
• Include headers

Example:

| Feature | Status | Notes       |
| ------- | ------ | ----------- |
| Auth    | ✅     | Complete    |
| API     | 🚧     | In progress |

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

```bash
npm install project-name
```

## Usage

```javascript
import { feature } from 'project-name'

feature.doSomething()
```

## Configuration

Available configuration options:

| Option  | Type   | Default | Description |
| ------- | ------ | ------- | ----------- |
| option1 | string | 'value' | Description |

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

## License

MIT License - see [LICENSE](./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.

```bash
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:**

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

**Example:**

```bash
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