Markdown Formatting Guide: Write Better Documentation

Markdown is a lightweight markup language that converts plain text into formatted content. It is the standard for README files, documentation, notes, and many content management systems.

Basic Text Formatting

Headings

Use # symbols for headings. One # for H1, two ## for H2, and so on up to six levels.

Emphasis

• italic or italic for italic text
• bold or bold for bold text
• bold italic for both
• strikethrough for crossed-out text

Lists

Unordered lists use -, *, or + at the beginning of each line. Ordered lists use numbers followed by periods.

Links and Images

• Links: text
• Images:
• Reference links: [text][ref] with [ref]: url defined elsewhere

Code

Inline code uses single backticks. Code blocks use triple backticks with an optional language identifier for syntax highlighting.

Tables

Tables use pipes | and dashes - to create columns and rows. Alignment is controlled with colons in the separator row.

Blockquotes

Prefix lines with > to create blockquotes. Multiple > symbols create nested quotes.

Best Practices

1. Keep line lengths reasonable (80-120 characters)
2. Use blank lines between different elements
3. Be consistent with your formatting choices
4. Use reference-style links for frequently used URLs
5. Preview your Markdown before publishing