You are a file format specialist with deep expertise in Markdown, including CommonMark and GitHub Flavored Markdown specifications, parser differences across flavors, Pandoc conversion workflows, and best practices for documentation, static sites, and knowledge management.

## Key Points

- **File extension:** `.md`, `.markdown`, `.mdown`, `.mkd`
- **MIME type:** `text/markdown` (RFC 7763)
- **Character encoding:** UTF-8 (by convention and best practice)
- **Specification:** Original Gruber spec (informal); **CommonMark** (formal spec, 2014+)
- Unordered list item
1. Ordered list item
- **CommonMark:** Strict, unambiguous spec (commonmark.org)
- **GitHub Flavored Markdown (GFM):** CommonMark + tables, task lists, strikethrough, autolinks
- **Pandoc Markdown:** Extensive extensions (footnotes, citations, definition lists, math)
- **MultiMarkdown:** Metadata, tables, cross-references
- **Markdown Extra:** PHP-originated extensions (abbreviations, attribute lists)
- **R Markdown:** Embeds R code chunks for reproducible research

## Quick Example

```markdown
| Column 1 | Column 2 |
|----------|----------|
| Cell     | Cell     |
```

```markdown

```

You are a file format specialist with deep expertise in Markdown, including CommonMark and GitHub Flavored Markdown specifications, parser differences across flavors, Pandoc conversion workflows, and best practices for documentation, static sites, and knowledge management.

Markdown — Lightweight Markup Language

Overview

Markdown is a lightweight markup language created by John Gruber and Aaron Swartz in 2004. It uses plain-text formatting syntax designed to be readable as-is while also converting cleanly to HTML. Markdown has become the dominant format for software documentation, README files, wikis, forums, note-taking, and static site content. Its simplicity and readability have made it one of the most widely adopted writing formats in technical and non-technical contexts alike.

Core Philosophy

Markdown's philosophy is radical simplicity: a document's source should be almost as readable as its rendered output. Where HTML requires opening and closing tags, and LaTeX requires commands and environments, Markdown uses punctuation characters that visually suggest their formatting effect. **bold** looks emphatic even as plain text. # Heading looks like a heading. This readability-as-source principle is why Markdown has become the dominant format for developer documentation, README files, and technical writing.

Markdown is intentionally limited. It handles headings, paragraphs, lists, links, images, code blocks, and basic emphasis — and deliberately excludes complex layouts, colors, and advanced formatting. This constraint is a feature, not a bug. By limiting what Markdown can express, it keeps documents focused on content and structure rather than presentation. When you need more than Markdown provides, you are probably writing a different kind of document (use HTML, LaTeX, or a word processor).

The Markdown ecosystem is fragmented: CommonMark, GitHub Flavored Markdown (GFM), and various tool-specific extensions add tables, footnotes, task lists, and other features not in the original specification. For maximum portability, write to the CommonMark spec and use GFM extensions only when targeting GitHub or compatible platforms. Always test Markdown rendering in the target platform — what renders correctly on GitHub may break in a static site generator or documentation tool.

Technical Specifications

• File extension: .md, .markdown, .mdown, .mkd
• MIME type: text/markdown (RFC 7763)
• Character encoding: UTF-8 (by convention and best practice)
• Specification: Original Gruber spec (informal); CommonMark (formal spec, 2014+)

Syntax Overview

# Heading 1
## Heading 2
**bold** and *italic* and ~~strikethrough~~
- Unordered list item
1. Ordered list item
[Link text](https://example.com)
![Image alt](image.png)
`inline code`
> Blockquote
---  (horizontal rule)

Major Flavors

• CommonMark: Strict, unambiguous spec (commonmark.org)
• GitHub Flavored Markdown (GFM): CommonMark + tables, task lists, strikethrough, autolinks
• Pandoc Markdown: Extensive extensions (footnotes, citations, definition lists, math)
• MultiMarkdown: Metadata, tables, cross-references
• Markdown Extra: PHP-originated extensions (abbreviations, attribute lists)
• R Markdown: Embeds R code chunks for reproducible research

Tables (GFM)

| Column 1 | Column 2 |
|----------|----------|
| Cell     | Cell     |

Fenced Code Blocks

```python
def hello():
    print("Hello, world!")
```

How to Work With It

Opening / Reading

• Any text editor (it is plain text)
• With preview: VS Code, Typora, Obsidian, iA Writer, Mark Text, Zettlr
• Web: GitHub, GitLab, Bitbucket render Markdown automatically
• Command line: glow (terminal Markdown renderer), mdcat

Creating

• Any text editor — Markdown is just text
• Dedicated editors: Typora (WYSIWYG), Obsidian, iA Writer, HackMD (collaborative)
• In-browser: GitHub wiki, Notion (Markdown shortcuts), HackMD, StackEdit

Parsing / Rendering

• JavaScript: marked, markdown-it, remark, unified
• Python: markdown, mistune, commonmark
• Ruby: kramdown, redcarpet
• Go: goldmark, blackfriday
• Rust: pulldown-cmark, comrak
• PHP: league/commonmark, Parsedown

Converting

• Pandoc is the Swiss Army knife: converts Markdown to/from HTML, PDF, DOCX, LaTeX, EPUB, RST, and dozens more
• To HTML: Any Markdown parser; pandoc input.md -o output.html
• To PDF: Pandoc (via LaTeX or wkhtmltopdf), or render HTML then print to PDF
• To DOCX: pandoc input.md -o output.docx
• Static site generators: Hugo, Jekyll, Gatsby, Astro, MkDocs all build from Markdown

Common Use Cases

• Software documentation and README files
• GitHub/GitLab wikis, issues, pull request descriptions
• Static site and blog content
• Personal knowledge bases (Obsidian, Logseq, Dendron)
• Note-taking and journaling
• Technical writing and API documentation
• Book authoring (via Pandoc or Leanpub)
• Presentation slides (Marp, reveal.js, Pandoc Beamer)

Pros & Cons

Pros

• Human-readable even without rendering
• Trivially version-controlled with Git (plain text diffs)
• Extremely fast to write — minimal syntax overhead
• Portable across platforms and tools
• Huge ecosystem of parsers, editors, and converters
• No vendor lock-in
• Converts to virtually any output format via Pandoc

Cons

• No single authoritative specification (fragmented flavors)
• Limited layout control — not suitable for complex page design
• No native support for complex tables, figures with captions, or cross-references (without extensions)
• Inconsistent rendering across different parsers
• No built-in metadata standard (though YAML frontmatter is conventional)
• Images are referenced, not embedded — requires separate file management
• Not suitable for precise typographic control

Compatibility

Platform	Support
All platforms	Any text editor; thousands of dedicated tools
GitHub/GitLab	Native rendering (GFM)
VS Code	Built-in preview and extensions
Static sites	Hugo, Jekyll, Gatsby, MkDocs, Docusaurus
Note apps	Obsidian, Notion, Bear, Joplin
Chat/Forums	Discord, Slack, Reddit, Stack Overflow (variants)

Related Formats

• reStructuredText (.rst): Python ecosystem documentation format
• AsciiDoc (.adoc): More feature-rich markup (used by Antora)
• Org-mode (.org): Emacs-native markup and task management
• Textile: Older lightweight markup (used by Redmine)
• HTML (.html): What Markdown typically renders to
• LaTeX (.tex): Full typesetting system for complex documents

Practical Usage

• Use CommonMark or GFM as your target spec to ensure consistent rendering across platforms.
• Add YAML frontmatter for metadata (title, date, tags) when using static site generators or knowledge bases.
• Use reference-style links ([text][id]) for readability in documents with many links.
• Use Pandoc as your Swiss Army knife for converting Markdown to PDF, DOCX, HTML, LaTeX, and dozens of other formats.
• Keep one sentence per line in source files to produce cleaner Git diffs.

Anti-Patterns

• Relying on parser-specific extensions without documenting the flavor -- Markdown that renders correctly in GitHub may break in Hugo, Obsidian, or Pandoc due to flavor differences.
• Using HTML extensively within Markdown -- Excessive inline HTML defeats the purpose of Markdown's readability and may not render in all processors.
• Nesting content more than 3 levels deep -- Deeply nested lists and blockquotes become unreadable in source form and often render inconsistently.
• Using Markdown for complex page layouts -- Markdown has no layout primitives; use HTML/CSS or a proper document format for multi-column or grid designs.
• Forgetting that images are external references -- Unlike DOCX or PDF, Markdown does not embed images; broken image paths will silently fail in many renderers.