DEV Community

Cover image for Markdown Style Guide: Best Practices for Content Creation
Quesby
Quesby

Posted on • Originally published at quesby.dev

Markdown Style Guide: Best Practices for Content Creation

#frontend #webdev #markdown

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)
Enter fullscreen mode Exit fullscreen mode

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___
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Ordered Lists 

1. First step
2. Second step
   1. Sub-step
   2. Another sub-step
3. Third step
Enter fullscreen mode Exit fullscreen mode

Task Lists 

- [x] Completed task
- [ ] Pending task
- [ ] Another pending task
Enter fullscreen mode Exit fullscreen mode

Links and References

Basic Links 

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

Reference Links 

[Link text][reference-id]

[reference-id]: https://example.com "Optional title"
Enter fullscreen mode Exit fullscreen mode

Email Links 

[Contact us](mailto:hello@example.com)
Enter fullscreen mode Exit fullscreen mode

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")
Enter fullscreen mode Exit fullscreen mode

Responsive Images 

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

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.
Enter fullscreen mode Exit fullscreen mode

Code Blocks 

function greetUser(name) {
  console.log(`Hello, ${name}!`);
}
Enter fullscreen mode Exit fullscreen mode

Syntax Highlighting 

<div class="container">
  <h1>Welcome</h1>
</div>
Enter fullscreen mode Exit fullscreen mode 
.container {
  max-width: 1200px;
  margin: 0 auto;
}
Enter fullscreen mode Exit fullscreen mode 
npm install package-name
Enter fullscreen mode Exit fullscreen mode

Fenced Code Blocks with Language 

{
  "name": "project",
  "version": "1.0.0",
  "dependencies": {
    "react": "^18.0.0"
  }
}
Enter fullscreen mode Exit fullscreen mode

Tables and Data

Basic Table 

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Row 1    | Data 1   | Data 2   |
| Row 2    | Data 3   | Data 4   |
Enter fullscreen mode Exit fullscreen mode

Aligned Table 

| Left Aligned | Center Aligned | Right Aligned |
|:-------------|:--------------:|--------------:|
| Left         | Center         | Right         |
| Data         | Data           | Data          |
Enter fullscreen mode Exit fullscreen mode

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 |
Enter fullscreen mode Exit fullscreen mode

Blockquotes and Callouts

Basic Blockquotes 

> This is a blockquote.
> It can span multiple lines.
> 
> And include multiple paragraphs.
Enter fullscreen mode Exit fullscreen mode

Nested Blockquotes 

> This is a blockquote.
> 
> > This is a nested blockquote.
> > It can be useful for replies or comments.
Enter fullscreen mode Exit fullscreen mode

Blockquotes with Attribution 

> The best way to predict the future is to create it.
> 
> — Peter Drucker
Enter fullscreen mode Exit fullscreen mode

Horizontal Rules and Separators 

---

***

___

- - -

* * *
Enter fullscreen mode Exit fullscreen mode

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~~
Enter fullscreen mode Exit fullscreen mode

Superscript and Subscript 

H~2~O (subscript)
2^10^ = 1024 (superscript)
Enter fullscreen mode Exit fullscreen mode

Highlighting 

==This text is highlighted==
Enter fullscreen mode Exit fullscreen mode

Footnotes 

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

[^1]: This is the footnote content.
Enter fullscreen mode Exit fullscreen mode

Content Structure Best Practices

1. Use Descriptive Headers 

❌ Bad
## Stuff

✅ Good
## User Authentication Methods
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

Accessibility Guidelines

1. Meaningful Alt Text 

❌ Bad
![image](photo.jpg)

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

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.
Enter fullscreen mode Exit fullscreen mode

3. Proper Heading Hierarchy 

# Main Title
## Section 1
### Subsection 1.1
### Subsection 1.2
## Section 2
### Subsection 2.1
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

2. Missing Alt Text 

❌ Bad
![Screenshot](image.jpg)

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

3. Poor Link Text 

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

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

4. Inconsistent Header Usage 

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

✅ Good
# Title
## Subtitle
## Another Section
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)