Markdown

General Principles

Write clear, accessible, and maintainable documentation using Markdown that renders consistently across platforms.

Document Structure

Frontmatter

Use YAML frontmatter for metadata:

---
title: Document Title
description: Brief description of the document
date: 2025-01-15
tags: [documentation, guide]
---

File Naming

Use lowercase with hyphens for file names:

✅ getting-started.md
✅ api-reference.md
❌ GettingStarted.md
❌ API_Reference.md

Headers

Hierarchy

Use ATX-style headers with proper hierarchy:

# Document Title (H1) - Use once per document

## Main Section (H2)

### Subsection (H3)

#### Detail Section (H4)

Header Spacing

Add blank lines before and after headers:

Some content here.

## New Section

Content starts here.

Header Capitalization

Use sentence case for headers:

✅ ## Getting started with the API
✅ ## Installation guide
❌ ## Getting Started With The API
❌ ## INSTALLATION GUIDE

Lists

Unordered Lists

Use hyphens for consistency:

- First item
- Second item
  - Nested item
  - Another nested item
- Third item

Ordered Lists

Use sequential numbering for readability:

1. First step
2. Second step
3. Third step

For long lists that may change, lazy numbering is acceptable:

1. First item
1. Second item
1. Third item

Task Lists

Use GitHub-style task lists:

- [x] Completed task
- [ ] Pending task
- [ ] Another pending task

Links

Inline Links

Prefer inline links for short URLs:

Check the [documentation](https://example.com/docs) for details.

Reference Links

Use reference links for repeated URLs or long URLs:

See the [API docs][api] and [user guide][guide] for more information.

[api]: https://example.com/api/reference
[guide]: https://example.com/user-guide

Link Text

Use descriptive link text:

✅ Read the [installation guide](link) for setup instructions.
❌ Click [here](link) to read the installation guide.

Code

Inline Code

Use backticks for inline code:

The `console.log()` function outputs to the console.

Code Blocks

Always specify the language for syntax highlighting:

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

```bash
npm install package-name
```

```json
{
  "name": "example",
  "version": "1.0.0"
}
```

File Paths

Format file paths as inline code:

Edit the `src/config.js` file to update settings.

Images

Basic Images

Always include descriptive alt text:

![User dashboard showing analytics](./images/dashboard.png)

Linked Images

Wrap images in links when needed:

[![Project logo](./logo.png)](https://example.com)

Image Sizing (HTML)

Use HTML when you need specific dimensions:

<img src="./diagram.png" alt="System architecture diagram" width="600">

Tables

Use pipe tables with proper alignment:

| Feature     | Description                | Status      |
| ----------- | -------------------------- | ----------- |
| API         | RESTful API endpoints      | ✅ Complete |
| Auth        | OAuth2 authentication      | 🚧 In progress |
| Docs        | User documentation         | ✅ Complete |

Alignment options:

| Left aligned | Center aligned | Right aligned |
| :----------- | :------------: | ------------: |
| Left         | Center         | Right         |

Emphasis

Bold and Italic

Use asterisks for consistency:

*italic text*
**bold text**
***bold and italic***

Strikethrough

Use tildes for strikethrough (GitHub Flavored Markdown):

~~strikethrough text~~

Line Length

Prose

Use 100-120 characters for prose to balance readability and version control:

This is a longer paragraph that demonstrates proper line length. The goal is
to keep lines readable while maintaining good git diff behavior. Break lines
at natural points like sentence boundaries.

Code and URLs

Don’t break long URLs or code blocks for readability.

Formatting

Line Breaks

Use blank lines between blocks:

Paragraph one.

Paragraph two.

- List item
- Another item

For hard line breaks within a paragraph, end with two spaces or use <br>:

First line
Second line

Or:

First line<br>
Second line

Horizontal Rules

Use three hyphens with blank lines:

Content above.

---

Content below.

Accessibility

Alt Text

Provide meaningful alt text for all images:

✅ ![Bar chart showing monthly sales increase from Jan to Dec](./sales-chart.png)
❌ ![chart](./sales-chart.png)
❌ ![](./sales-chart.png)

Descriptive Links

Use clear, descriptive link text:

✅ Download the [user manual (PDF, 2MB)](./manual.pdf)
❌ Download the user manual [here](./manual.pdf)

Document Structure

Use proper heading hierarchy for screen readers:

# Main Title (H1)
## Section (H2)
### Subsection (H3)

Don’t skip heading levels:

❌ # Title
   ### Subsection (skipped H2)

Modern Markdown Features

GitHub Flavored Markdown

Support for additional features:

- [x] Task lists
- [ ] Unchecked items

:emoji: Emoji support

~~Strikethrough~~

Tables with alignment

Admonitions/Callouts

Use HTML for callouts when Markdown doesn’t support them:

> **Note**: This is important information.

> **Warning**: Be careful with this operation.

> **Tip**: You can optimize performance by...

HTML in Markdown

Use HTML when needed for accessibility or styling:

<details>
<summary>Click to expand</summary>

Hidden content here.

</details>

<abbr title="HyperText Markup Language">HTML</abbr>

Best Practices

Do’s

✅ Use consistent formatting throughout ✅ Include descriptive alt text for images ✅ Specify language for code blocks ✅ Use proper heading hierarchy ✅ Add blank lines between blocks ✅ Use descriptive link text ✅ Keep line length reasonable (100-120 chars for prose) ✅ Use HTML for accessibility features

Don’ts

❌ Skip heading levels ❌ Use generic link text (“click here”) ❌ Forget alt text for images ❌ Mix different list styles ❌ Use HTML for simple formatting ❌ Leave trailing whitespace ❌ Use tabs for indentation

Markdown Flavors

Be aware of different Markdown implementations:

• CommonMark - Standard specification
• GitHub Flavored Markdown (GFM) - Adds tables, task lists, strikethrough
• MDX - Markdown with JSX/React components
• Markdown + Frontmatter - Used by static site generators

Test your documentation on your target platform.

Tools

Recommended Tools

• Prettier - Markdown formatting
• markdownlint - Linting and style checking
• Vale - Prose style linting
• MDX - Markdown with components
• Remark - Markdown processor

Editor Extensions

• VS Code: Markdown All in One, markdownlint
• Vim: vim-markdown, markdown-preview
• Sublime Text: MarkdownEditing

Resources

• CommonMark Spec
• GitHub Flavored Markdown
• Markdown Guide
• MDN: Writing Markdown