Skip to content

Markdown

Markdown style guidelines#

This document defines the Markdown style guidelines for all Markdown files in this repository. These rules follow common Markdown linter best practices and ensure consistency across documentation.

Headings#

  • Use ATX-style headings (#) instead of Setext-style (underlines)
  • Include a space after the hash marks: # Heading not #Heading
  • Use only one top-level heading (#) per document
  • Do not skip heading levels (e.g., don't go from # to ###)
  • Surround headings with blank lines (one before, one after, excluding the first heading in the document unless preceded by frontmatter)
  • Do not use trailing punctuation in headings (no periods, colons, etc.)
  • Use sentence case for headings unless referring to proper nouns or code identifiers

Good:

# Main heading

## Subsection

### Details

Bad:

#No space after hash
### Skipped level 2
## Heading with period.

Lists#

  • Use consistent list markers throughout the document (- for unordered, 1. for ordered)
  • Do not add blank lines between list items (unless item contains multiple paragraphs)
  • Indent nested lists by 2 spaces for unordered, 3 spaces for ordered
  • Use 1. for all ordered list items (auto-numbering) or number them sequentially
  • Surround lists with blank lines (one before, one after)
  • Use - for unordered lists (not * or +)

Good:

Here is a list:

- First item
- Second item
- Third item

Another list:

1. First step
1. Second step
1. Third step

Bad:

No blank line before list:
- Item one

- Blank lines between items
- Not needed

* Wrong marker
+ Mixed markers

Code Blocks#

  • Always use fenced code blocks (triple backticks) with language identifiers
  • Always include a blank line before and after code blocks
  • Specify the language for syntax highlighting (bash, python, markdown, json, etc.)
  • Use plaintext or text if no specific language applies
  • Indent code blocks at the same level as surrounding content

Good:

Here is an example:

\`\`\`bash
echo "Hello, world!"
\`\`\`

The command prints a message.

Bad:

No language identifier:
\`\`\`
code here
\`\`\`
No blank lines before/after code blocks.
  • Use reference-style links for repeated URLs
  • Use relative paths for internal links (relative to the current file)
  • Always provide link text in square brackets: [text](url)
  • Do not use bare URLs (wrap them: <https://example.com>)
  • For internal repository links, use relative paths starting with ./ or ../
  • Use .md extension for links to Markdown files

Good:

See the [installation guide](../docs/installation.md) for details.

Check out [GitHub][gh] and [GitLab][gl] for hosting.

[gh]: https://github.com
[gl]: https://gitlab.com

Bad:

Absolute path: [guide](/docs/installation.md)
Missing extension: [guide](../docs/installation)
Bare URL: Visit https://example.com

Tables#

  • Use tables when content follows a consistent structure (instead of lists)
  • Align columns using hyphens for readability
  • Include header row separator with at least 3 hyphens per column
  • Surround tables with blank lines (one before, one after)
  • Use pipes (|) to separate columns
  • Align content within columns for readability (optional but recommended)

Good:

Here is a comparison:

| Feature | Supported | Notes |
|---------|-----------|-------|
| Feature A | Yes | Fully supported |
| Feature B | No | Planned for v2 |
| Feature C | Partial | Beta feature |

The table shows current status.

Bad:

Using list when table is better:
- Feature A: Yes - Fully supported
- Feature B: No - Planned for v2
- Feature C: Partial - Beta feature

Requirement Number Formatting#

When writing or referencing requirement numbers (NFR and FR) in documentation: - Always use bold formatting for requirement numbers - Replace hyphens with non-breaking hyphens (&#8209;) between letters and numbers - This prevents line breaks within requirement numbers and ensures consistent formatting - This applies to all specification documents, plans, and tables

Examples: 

# Correct formatting
**NFR&#8209;001**: The system must respond within 200ms
**FR&#8209;042**: User authentication shall support OAuth 2.0

# In tables
| ID | Description |
|----|-------------|
| **NFR&#8209;001** | Performance requirement |
| **FR&#8209;042** | Authentication feature |

# Incorrect formatting (do not use)
NFR-001: Without bold or non-breaking hyphen
**NFR-001**: Bold but with regular hyphen (can break across lines)
NFR&#8209;001: Non-breaking hyphen but not bold

Emphasis#

  • Use * or _ for emphasis (italic), ** or __ for strong emphasis (bold)
  • Be consistent within a document (prefer * and **)
  • Do not use emphasis for headings
  • Use backticks for code/technical terms, not emphasis

Good:

This is *emphasized* text.
This is **strong** text.
Use the `--verbose` flag for details.

Bad:

This is _emphasized_ text with **strong** mixed styles.
Use the *--verbose* flag (should be backticks).

Line Length#

  • Wrap prose at 80-120 characters per line
  • Do not wrap code blocks, tables, or URLs
  • Break after sentences or at natural phrase boundaries
  • Empty lines do not count toward line length

Whitespace#

  • Use a single blank line to separate blocks of content
  • Do not use multiple consecutive blank lines
  • End files with a single newline character
  • Do not use trailing whitespace at the end of lines
  • Use spaces (not tabs) for indentation

Other Rules#

Horizontal Rules#

  • Use three hyphens (---) for horizontal rules
  • Surround horizontal rules with blank lines

Good:

Section one content.

---

Section two content.

Blockquotes#

  • Use > for blockquotes with a space after
  • Surround blockquotes with blank lines
  • Use multiple > for nested quotes

Good:

As the docs state:

> This is an important note.
> It spans multiple lines.

Back to regular text.

Images#

  • Use alt text for all images: ![alt text](path/to/image.png)
  • Use relative paths for repository images
  • Prefer reference-style for repeated images

Good:

![Architecture diagram](../media/architecture.png)

See the [logo][logo-img] above.

[logo-img]: ./images/logo.png

HTML#

  • Avoid HTML in Markdown when possible
  • Use HTML only for features not supported by Markdown
  • Close all HTML tags properly

Filenames#

  • Use lowercase for Markdown filenames
  • Use hyphens (-) not underscores (_) to separate words
  • Use .md extension (not .markdown)

Examples:

  • installation-guide.md ✅
  • Installation_Guide.markdown ❌

Linting#

To validate Markdown files against these guidelines, use a Markdown linter such as:

Configure the linter to enforce these rules in your CI/CD pipeline.