CodeCraft
← Back to Blog
Tutorial2026-04-23·9 min read

Markdown Guide: From Basics to Advanced Formatting

#markdown#gfm#commonmark#documentation#writing
C
CodeCraft Team· Engineering

Markdown is a lightweight markup language created by John Gruber in 2004 with the goal of being readable as plain text while also convertible to HTML. Today it powers GitHub READMEs, technical documentation sites (MkDocs, Docusaurus), note-taking apps (Obsidian, Notion), and most modern content management systems.

This guide covers Markdown syntax from basics to advanced features including tables, task lists, code blocks, and GitHub Flavored Markdown (GFM) extensions.

Basic Markdown Syntax

Headings use pound signs:

# Heading 1
## Heading 2
### Heading 3
#### Heading 4

Emphasis:

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

Lists:

- Unordered item
- Another item
  - Nested item (indent 2 spaces)

1. Ordered item
2. Second item
   1. Nested ordered

Links and images:

[Link text](https://example.com)
[Link with title](https://example.com "Hover title")
![Alt text](image.png)
![Alt text](image.png "Image title")

Blockquotes:

> This is a blockquote
> It can span multiple lines
>
> With empty lines for paragraphs

Horizontal rules:

---
***
___

Code Blocks and Syntax Highlighting

Inline code uses single backticks: const x = 1

Fenced code blocks use triple backticks with optional language identifier:

function greet(name) {

return Hello, ${name}!;

}

Supported language identifiers include: javascript, typescript, python, rust, go, java, sql, bash, yaml, json, xml, css, html, and many more.

Indented code blocks (4 spaces) are an older syntax:

    This is an indented code block
    It preserves whitespace

Most renderers support syntax highlighting for fenced blocks with a language tag. GitHub, GitLab, and most documentation tools process these using highlight.js or Prism.js.

GitHub Flavored Markdown (GFM) Extensions

GitHub extended standard Markdown with several useful features, now widely adopted by other platforms.

Tables:

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Left     | Center   | Right    |

| Left-aligned | Center-aligned | Right-aligned |
|:-------------|:--------------:|--------------:|
| A            | B              | C             |

Task lists (checkboxes):

- [x] Completed task
- [ ] Pending task
- [x] Another done item
  - [ ] Nested task

Autolinks:

https://example.com  (automatically linked)
[email protected]     (email autolinked)

Footnotes (supported by many renderers):

This sentence has a footnote[^1].

[^1]: This is the footnote content.

Definition lists (supported by Pandoc, MkDocs):

Term
: Definition of the term

Another term
: Another definition

Advanced: Escaping, HTML, and Edge Cases

Escaping special characters -- backslash before any Markdown character:

\*Not italic\*
\[Not a link\](https://example.com)

Inline HTML is allowed in most Markdown renderers:

This has <span style="color:red">red text</span>.

<details>
<summary>Click to expand</summary>

Content that is hidden by default.

</details>

Embedding images with size control (HTML required):

<img src="image.png" alt="Alt text" width="400">

Common Markdown gotchas:

- Two spaces at end of line = line break; empty line = paragraph break

- Four-space indent = code block (even inside lists)

- Links can use reference style: [text][ref] and [ref]: url

- Nested lists require consistent indentation (2 or 4 spaces)

- Some renderers require blank lines before/after lists and headings

Markdown Variants and Tooling

There is no single Markdown standard -- different implementations vary:

CommonMark -- the most strictly specified standard, used as a base by GitHub, Reddit, Stack Overflow, and Discourse. The spec at commonmark.org resolves all ambiguities in the original Markdown.

GitHub Flavored Markdown (GFM) -- CommonMark + tables, strikethrough, task lists, autolinks.

Pandoc Markdown -- the most feature-rich variant, adding citations, definition lists, superscript, subscript, and multi-format output (PDF, DOCX, LaTeX).

MDX -- Markdown + JSX components, used with React documentation tools like Docusaurus and Nextra.

Popular Markdown tools:

- Obsidian -- note-taking with graph view

- Typora -- WYSIWYG Markdown editor

- MkDocs / Docusaurus -- documentation site generators

- Marked.js / markdown-it -- JavaScript Markdown parsers

- Pandoc -- universal document converter

# Convert Markdown to PDF with Pandoc:
pandoc input.md -o output.pdf --pdf-engine=xelatex

# Convert Markdown to DOCX:
pandoc input.md -o output.docx
Markdown's power lies in its simplicity -- a small grammar that can be typed as plain text and rendered beautifully in any context. From GitHub READMEs and documentation sites to note-taking apps and blog platforms, Markdown has become the universal writing language for developers. Use our Markdown Editor to write and preview Markdown in real time, with support for GitHub Flavored Markdown syntax.