Markdown Essentials

Markdown is plain text with intent. You write **bold** and it renders bold. No XML soup. No hidden formatting. What you type is what you get.

Why Markdown Matters

1. Portable - Works everywhere: GitHub, Notion, VSCode, static site generators
2. Readable - Source code is human-readable before rendering
3. Version control friendly - Git diffs make sense
4. Fast - No toolbar clicking, no mouse needed
5. LLM-native - AI models love Markdown (more on this below)

LLMs and Markdown: A Perfect Match

Large Language Models don’t just produce Markdown - they consume it exceptionally well. Here’s why:

Structured yet flexible: Markdown’s syntax is clear enough for models to parse structure (headers, lists, code blocks) but simple enough to generate reliably. No unclosed tags. No broken HTML.

Training data: Most technical documentation, GitHub repos, and forums use Markdown. LLMs have seen billions of Markdown documents during training. It’s their native language.

Bidirectional workflow:

• Ask an LLM to write documentation → You get clean Markdown
• Feed Markdown to an LLM → It understands structure, hierarchy, and emphasis
• Edit with AI assistance → Models can modify Markdown precisely without breaking formatting

Prompt engineering: Want better LLM responses? Ask for Markdown output. The structure forces clarity. Bullet points over paragraphs. Code blocks over inline mentions. Headers for organization.

Example prompt:

Explain JWT authentication in Markdown format with:
- ## sections for main concepts
- Code examples in ```typescript``` blocks
- Bullet points for pros/cons

You get structured, scannable output instead of a wall of text.

The loop closes: You write in Markdown. AI reads it. AI writes more Markdown. You read it. The format never breaks. Compare this to asking an LLM to edit a Word document.

The Core Syntax

Headers

# H1 - Main Title
## H2 - Section
### H3 - Subsection

Emphasis

*italic* or _italic_ → italic **bold** or __bold__ → bold ***bold italic*** → bold italic ~~strikethrough~~ → strikethrough

Lists

Unordered:

- Item one
- Item two
  - Nested item
  - Another nested

Ordered:

1. First step
2. Second step
3. Third step

Links and Images

[Link text](https://example.com) → Link text

Images use the same syntax with ! prefix: ![Alt text](image.jpg)

Code

Inline code: `code here` → code here

Code blocks:

```javascript
function hello() {
  console.log("Hello, world!");
}
```

Blockquotes

> This is a quote.
> It can span multiple lines.
>
> Even with paragraph breaks.

Horizontal Rules

---
or
***
or
___

Tables

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

Alignment:

| Left | Center | Right |
|:-----|:------:|------:|
| L    |   C    |     R |

Advanced: Task Lists

- [x] Completed task
- [ ] Incomplete task
- [ ] Another incomplete task

Common Pitfalls

1. Escaping special characters - Use backslash: \*not italic\*
2. Spaces matter - Lists need consistent indentation
3. Line breaks - Two spaces at end of line for <br>, or use blank line for new paragraph
4. Nested lists - Indent with 2-4 spaces (be consistent)

Flavors Matter

Markdown has variants:

• CommonMark - Standardized specification
• GitHub Flavored Markdown (GFM) - Adds tables, task lists, strikethrough
• MDX - Markdown + JSX components (this blog uses it)

Know your renderer’s flavor. Not all features work everywhere.

The Philosophy

Markdown follows the “checkpoint” principle. Write content in a format that survives:

• Technology changes
• Platform migrations
• Tool replacements

The text is yours. Forever.

Plain text files from 1985 still open. Will your Medium posts from 2023?

Tools

Editors:

• VSCode with Markdown extensions
• Typora (WYSIWYG)
• Obsidian (knowledge base)

Converters:

• Pandoc - convert to/from anything
• Marked 2 - preview and export (macOS)

Linters:

• markdownlint - enforce consistent style
• markdown-link-check - validate links

See It In Action

Here are complex examples showing raw Markdown and their rendered output:

Example 1: Nested Lists with Links

Raw:

## Project Setup

1. **Install dependencies**
   - Run `npm install` or `yarn install`
   - Check the [documentation](https://docs.example.com)
2. **Configure environment**
   - Copy `.env.example` to `.env`
   - Update API keys
3. **Start development server**
   ```bash
   npm run dev

**Renders as:**

## Project Setup

1. **Install dependencies**
   - Run `npm install` or `yarn install`
   - Check the [documentation](https://docs.example.com)
2. **Configure environment**
   - Copy `.env.example` to `.env`
   - Update API keys
3. **Start development server**
   ```bash
   npm run dev

---

Example 2: Blockquote with Code

Raw:

> **Tip:** Always validate user input.
>
> ```javascript
> const sanitize = (input) => input.trim();
> ```
>
> This prevents common security issues.

Renders as:

Tip: Always validate user input.

const sanitize = (input) => input.trim();

This prevents common security issues.

---

Example 3: Table with Formatting

Raw:

| Feature | Status | Notes |
|---------|:------:|-------|
| **Auth** | ✅ | Using JWT |
| **API** | 🚧 | In progress |
| **Tests** | ❌ | [Planned](#roadmap) |

Renders as:

Feature	Status	Notes
Auth	✅	Using JWT
API	🚧	In progress
Tests	❌	Planned

---

Example 4: Task List with Context

Raw:

### Sprint Goals

- [x] Design user dashboard
- [x] Implement authentication
- [ ] Add data visualization
  - [x] Chart component
  - [ ] Real-time updates
- [ ] Write API documentation

Renders as:

Sprint Goals

• Design user dashboard
• Implement authentication
• Add data visualization
  • Chart component
  • Real-time updates
• Write API documentation

Quick Reference

# Headers (#, ##, ###)
**bold** *italic* ~~strike~~
[link](url) ![image](url)
`inline code`
```code block```
> quote
- list
1. ordered
| table |

That’s it. Everything else is decoration.

---

Next in series: Mermaid Diagrams - when text isn’t enough.

Part of the VSCode Content Creator workflow.