Markdown Mastery — Everything You Need for Technical Writing

Markdown is the lingua franca of technical writing. It’s simple enough to write in any editor, yet powerful enough for code, tables, and structured content. This guide covers the full spectrum.

Basic Syntax

You probably know the basics: **bold**, *italic*, # headings, - or * for lists. A few often-forgotten gems:

Strikethrough

Use ~~strikethrough~~ for deprecated outdated information.

Inline code

Wrap with backticks: `code`. For literal backticks, use double backticks: `` ` ``.

Links and images

Copy[link text](https://example.com)
![alt text](/path/to/image.png)

Code Blocks

Fenced code blocks with language tags enable syntax highlighting:

Copyfunction fibonacci(n) {
  if (n <= 1) return n;
  return fibonacci(n - 1) + fibonacci(n - 2);
}

Copydef greet(name: str) -> str:
    return f"Hello, {name}!"

Copynpm install
npm run build

Tables

GitHub-style tables are widely supported:

Feature	Supported	Notes
Headers	Yes	Use --- for alignment
Alignment	Yes	:--- left, :---: center
Cells	Yes	Pipe `

Blockquotes

Blockquotes are great for callouts, testimonials, or highlighting important points.

They can span multiple paragraphs. Just add a > to each line.

Nested Lists

1. First item
   • Nested unordered
   • Another nested
2. Second item
   • Indent with 2-4 spaces
   • Or a tab

Task Lists

• Completed task
• Another done item
• Pending task

Footnotes

Here’s a sentence with a footnote¹. And another reference².

Horizontal Rules

Use ---, ***, or ___ for a horizontal rule.

---

Best Practices

1. Use blank lines between block elements for consistent rendering
2. Add alt text to images for accessibility
3. Keep line length under 80-100 characters for diffs
4. Use semantic headings — don’t skip levels (h1 → h3)
5. Escape special characters when needed: \* for literal asterisk

Extensions

Many tools support extensions:

• MDX — JSX in Markdown for interactive components
• Admonitions — Custom block syntax for notes and warnings
• Math — LaTeX with $...$ for inline and $$...$$ for block
• Diagrams — Mermaid, PlantUML for flowcharts

---

Master these patterns and you’ll write faster, cleaner documentation that renders beautifully everywhere.

Footnotes

1. This is the first footnote. ↩

2. Footnotes can have formatting and code. ↩