Markdown syntax reference

Markdown is a lightweight markup language — plain text that renders as formatted HTML. The original spec was created by John Gruber in 2004. Here are the most useful constructs:

• Headings: # H1, ## H2, ### H3 (up to H6)
• Emphasis: **bold**, *italic*, ***bold italic***
• Inline code: backtick-wrapped text: `code`
• Code blocks: triple-backtick fences with optional language identifier
• Links: [text](url) or [text](url "title")
• Images: ![alt](url)
• Unordered lists: lines starting with -, *, or +
• Ordered lists: lines starting with 1., 2., etc.
• Blockquotes: lines starting with >
• Horizontal rules: three or more dashes (---)

GitHub Flavored Markdown: tables, task lists, strikethrough

GitHub Flavored Markdown (GFM) extends the original spec with several widely-adopted features. This tool renders all of them via remark-gfm:

• Tables: pipe-separated rows with a header separator (| --- |). Alignment is set with colons: :--- (left), ---: (right), :---: (center).
• Task lists: list items with - [ ] (unchecked) or - [x] (checked). Commonly used for todo lists and PR checklists.
• Strikethrough: wrap text in double tildes — ~~text~~ renders as text.
• Autolinks: bare URLs like https://example.com become clickable links without explicit bracket syntax.

Markdown vs MDX vs rich text

Markdown is the simplest option — plain text, widely understood, supported everywhere. Use it for documentation, READMEs, blog posts, and anywhere the content is text-dominant.

MDX extends Markdown with JSX — you can import React components directly into your content. This is powerful for documentation sites where you want interactive examples inline with prose. The trade-off is that MDX is tightly coupled to React and adds build-time complexity.

Rich text editors (like TipTap, Quill, or Notion-style blocks) are appropriate when non-technical users need to create content without writing markup. The output is typically a JSON document tree, not a string — which means querying, searching, and transforming it requires different tooling than plain Markdown.

Using Markdown in Next.js projects

The simplest approach for Next.js is react-markdown with remark-gfm. Both are already installed in this project. Pass a Markdown string as the child prop and an array of remark plugins:

For blog posts and documentation where content lives in .md files, gray-matter parses the YAML front matter, and remark/rehype pipelines handle the content. For performance, process Markdown on the server during the Next.js build or at request time using server components — this avoids shipping the Markdown parser to the browser.