Markdown Style Guide — Formatting Standards for Documentation Files

In this tutorial, you will learn about Markdown Style Guide. We cover key concepts, practical examples, and best practices to help you master this topic.

A markdown style guide defines how to use Markdown syntax consistently across documentation files. Consistent Markdown formatting makes files easier to read in raw form and produces predictable rendered output.

In this lesson, you will learn Markdown formatting rules that ensure consistency across your documentation.

What You'll Learn

You will understand Markdown style rules for headings, lists, code blocks, tables, links, and images.

Why It Matters

Consistent Markdown formatting prevents rendering issues, makes files easier to review, and ensures a uniform appearance across all documentation pages.

Real-World Use

DodaTech enforces Markdown style rules through Prettier and custom linters. All documentation files follow the same formatting automatically.

flowchart LR
  A[Markdown Guide] --> B[Headings]
  A --> C[Lists]
  A --> D[Code Blocks]
  A --> E[Tables]
  A --> F[Links]
  B --> G[Sentence Case]
  B --> H[Space After #]
  C --> I[Blank Lines]
  D --> J[Language Tags]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Heading Rules

Use a single h1 per page. The h1 should match the page title. Use sentence case for all headings.

Add a space after the hash marks. # Title not #Title. This is standard Markdown.

Add blank lines before and after headings. Headings need separation from content for readability.

Do not skip heading levels. Go from h2 to h3, not h2 to h4.

# Good heading structure

## Installation
### System requirements
### Step-by-step guide

## Configuration

# Bad heading structure
## Installation
#### System requirements (skipped h3)

List and Code Block Rules

Use consistent list markers. Use asterisks for bullet lists. Use numbers for ordered lists.

Add blank lines before and after lists. Lists need separation from surrounding paragraphs.

Use fenced code blocks with language tags. Indented code blocks do not support syntax highlighting.

Add blank lines before and after code blocks. Code blocks need visual separation.

# Good list formatting

Supported algorithms:
- Gzip: Fast compression
- Bzip2: Balanced ratio
- XZ: Maximum compression

# Good code block
```python
def compress(data):
    return gzip.compress(data)

Common Mistakes

1. No Space After Heading Hash

#Title instead of # Title. Some parsers fail without the space.

2. No Blank Lines Around Blocks

Lists, code blocks, and tables without blank lines around them can parse incorrectly.

3. Mixed List Markers

Using -, *, and + interchangeably in the same document. Pick one and be consistent.

4. No Language Tag in Code Blocks

Code blocks without language tags cannot get syntax highlighting.

5. Trailing Whitespace

Spaces at the end of lines that cause unwanted line breaks.

6. Inconsistent Table Alignment

Tables without alignment markers or with mismatched column counts.

7. Bare URLs

URLs displayed as full links instead of using descriptive link text.

Practice Questions

1. How many h1 headings should a page have?

One. The h1 should match the page title.

2. What case should headings use?

Sentence case. Only the first word and proper nouns are capitalized.

3. Why add blank lines around code blocks?

For readability and to prevent Parsing errors.

4. Why use language tags in code blocks?

For syntax highlighting. Without a language tag, the code block appears as plain text.

5. Challenge: Create a Markdown style guide with 10 rules. Include examples of good and bad formatting for each rule.

FAQ

Mini Project

Create a Markdown style guide with 15 rules covering headings, lists, code blocks, tables, links, and images. Include good and bad examples. Format a test page using the guide and review for consistency.

What's Next

Next: Abbreviations and Acronyms