Markdown Style Guide: Best Practices for Content Creation

Markdown has become the de facto standard for content creation in modern web development. Whether you're writing documentation, blog posts, or technical articles, understanding Markdown best practices ensures your content is readable, accessible, and maintainable.

This style guide covers everything from basic formatting to advanced techniques, helping you create content that works seamlessly across different platforms and devices.

Basic Text Formatting

Headers and Structure

Use header hierarchy to create clear content structure:

# Main Title (H1)
## Section Title (H2)
### Subsection (H3)
#### Minor Heading (H4)
##### Small Heading (H5)
###### Tiny Heading (H6)

Best Practice: Use only one H1 per document and maintain logical hierarchy. Don't skip heading levels.

Emphasis and Strong Text

*This text is italic*
_This text is also italic_

**This text is bold**
__This text is also bold__

***This text is both bold and italic***
___This text is also both___

Accessibility Tip: Use emphasis sparingly. Screen readers announce emphasis, so overuse can be distracting.

Lists and Organization

Unordered Lists

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

Ordered Lists

1. First step
2. Second step
   1. Sub-step
   2. Another sub-step
3. Third step

Task Lists

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

Links and References

Basic Links

[Link text](https://example.com)
[Link with title](https://example.com "Optional title")

Reference Links

[Link text][reference-id]

[reference-id]: https://example.com "Optional title"

Email Links

[Contact us](mailto:hello@example.com)

Best Practice: Use descriptive link text. Avoid "click here" or "read more" as they don't provide context when read out of context.

Images and Media

Basic Image Syntax

![Alt text](image.jpg)
![Alt text](image.jpg "Optional title")

Responsive Images

![Alt text](image.jpg "Title")
![Alt text](image-320.jpg "Title" width="320")
![Alt text](image-640.jpg "Title" width="640")

Accessibility: Always provide meaningful alt text. If an image is decorative, use empty alt text: ![](image.jpg)

Code and Technical Content

Inline Code

Use `console.log()` to output data to the browser console.

Code Blocks

```javascript
function greetUser(name) {
  console.log(`Hello, ${name}!`);
}
```

Syntax Highlighting

```html
<div class="container">
  <h1>Welcome</h1>
</div>
```

```css
.container {
  max-width: 1200px;
  margin: 0 auto;
}
```

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

Fenced Code Blocks with Language

```json
{
  "name": "project",
  "version": "1.0.0",
  "dependencies": {
    "react": "^18.0.0"
  }
}
```

Tables and Data

Basic Table

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Row 1    | Data 1   | Data 2   |
| Row 2    | Data 3   | Data 4   |

Aligned Table

| Left Aligned | Center Aligned | Right Aligned |
|:-------------|:--------------:|--------------:|
| Left         | Center         | Right         |
| Data         | Data           | Data          |

Complex Table

| Feature | Status | Notes |
|:--------|:------:|:------|
| Basic Auth | ✅ Complete | Works with all providers |
| OAuth 2.0 | 🚧 In Progress | Expected Q2 2024 |
| SSO | ❌ Planned | Not yet started |

Blockquotes and Callouts

Basic Blockquotes

> This is a blockquote.
> It can span multiple lines.
>
> And include multiple paragraphs.

Nested Blockquotes

> This is a blockquote.
>
> > This is a nested blockquote.
> > It can be useful for replies or comments.

Blockquotes with Attribution

> The best way to predict the future is to create it.
>
> — Peter Drucker

Horizontal Rules and Separators

---

***

___

- - -

* * *

Best Practice: Use horizontal rules sparingly to avoid visual clutter. They work best for major section breaks.

Advanced Markdown Features

Strikethrough

~~This text is crossed out~~

Superscript and Subscript

H~2~O (subscript)
2^10^ = 1024 (superscript)

Highlighting

==This text is highlighted==

Footnotes

This is a sentence with a footnote[^1].

[^1]: This is the footnote content.

Content Structure Best Practices

1. Use Descriptive Headers

❌ Bad
## Stuff

✅ Good
## User Authentication Methods

2. Keep Paragraphs Short

Break up long paragraphs into digestible chunks. Aim for 2-3 sentences per paragraph on mobile devices.

3. Use Lists for Scannable Content

❌ Bad
The application supports multiple features including user authentication, data validation, error handling, and logging.

✅ Good
The application supports multiple features:
- User authentication
- Data validation
- Error handling
- Logging

4. Include Table of Contents

For longer documents, consider adding a table of contents:

## Table of Contents
- [Introduction](#introduction)
- [Getting Started](#getting-started)
- [Configuration](#configuration)
- [Advanced Usage](#advanced-usage)
- [Troubleshooting](#troubleshooting)

Accessibility Guidelines

1. Meaningful Alt Text

❌ Bad
![image](photo.jpg)

✅ Good
![Screenshot of the login form showing username and password fields](login-form.jpg)

2. Descriptive Link Text

❌ Bad
[Click here](https://example.com) for more information.

✅ Good
[Read our complete installation guide](https://example.com) for detailed setup instructions.

3. Proper Heading Hierarchy

# Main Title
## Section 1
### Subsection 1.1
### Subsection 1.2
## Section 2
### Subsection 2.1

Platform-Specific Considerations

GitHub Flavored Markdown

• Supports task lists: - [x] Completed task
• Supports tables with alignment
• Supports strikethrough: ~~text~~
• Supports syntax highlighting in code blocks

CommonMark

• More standardized than GitHub Flavored Markdown
• Better cross-platform compatibility
• Supports most basic Markdown features

Static Site Generators

• Many support front matter (YAML, TOML, JSON)
• Some support custom shortcodes or components
• Consider your target platform's specific features

Tools and Resources

Markdown Editors

• VS Code: Built-in preview and extensions
• Typora: WYSIWYG Markdown editor
• Mark Text: Real-time preview editor
• Obsidian: Note-taking with Markdown support

Validation Tools

• markdownlint: Lint Markdown files
• markdown-link-check: Check for broken links
• textlint: Advanced text linting

Online Tools

• Dillinger: Online Markdown editor
• StackEdit: Advanced online editor
• Markdown Live Preview: Real-time preview

Common Mistakes to Avoid

1. Inconsistent Formatting

❌ Bad
- Item 1
* Item 2
- Item 3

✅ Good
- Item 1
- Item 2
- Item 3

2. Missing Alt Text

❌ Bad
![Screenshot](image.jpg)

✅ Good
![Screenshot of the dashboard showing user statistics](dashboard.jpg)

3. Poor Link Text

❌ Bad
[Here](https://example.com) is the documentation.

✅ Good
[Complete API documentation](https://example.com) is available online.

4. Inconsistent Header Usage

❌ Bad
# Title
### Subtitle
## Another Section

✅ Good
# Title
## Subtitle
## Another Section

Conclusion

Mastering Markdown is about more than just syntax—it's about creating content that is accessible, maintainable, and user-friendly. By following these best practices, you'll create documentation and content that serves your users well across all platforms and devices.

Remember:

• Consistency is key to maintainable content
• Accessibility should be considered from the start
• Structure helps both humans and machines understand your content
• Testing your Markdown across different platforms ensures compatibility

Start implementing these practices in your next piece of content, and you'll see immediate improvements in readability and maintainability.

This style guide is part of the Quesby project, a privacy-first static site boilerplate. For more resources and examples, visit our GitHub repository.