Markdown Guide: Write Faster, Format Better, Publish Anywhere

The Writing Format That Works Everywhere

There is a format that GitHub renders as beautiful documentation, that Jekyll and Hugo turn into blog posts, that VS Code previews inline, that Reddit uses for post formatting, that Discord applies to messages, that Notion accepts as input, and that every static site generator on the planet supports natively. That format is Markdown.

Created by John Gruber in 2004 with the core philosophy that it should be readable as plain text even without rendering, Markdown has become the de facto standard for technical writing, documentation, README files, blog content, and developer communication. If you write anything that involves formatted text, understanding Markdown deeply will save you hours.

This guide covers every syntax element with real examples, explains the variants and extensions, and addresses how to work with Markdown efficiently.

---

Why Markdown Instead of a Word Processor?

The case for Markdown is not just preference — it solves real problems that rich text editors create.

Plain text is universal and future-proof. A .md file will be readable in any text editor on any operating system in 50 years. Microsoft Word files require Microsoft Word. Rich text in a CMS requires that CMS.

Version control friendly. Git diffs on Markdown files show exactly what changed in a document. Word documents produce binary diffs that are unreadable.

Separation of content and presentation. You write content; the renderer handles presentation. This lets the same Markdown content be styled differently on different platforms without changing the source.

Speed. Once syntax is internalized, formatting with Markdown is faster than reaching for a toolbar — **bold** is faster than Ctrl+B when your hands are already on the keyboard.

Platform support. It works in GitHub, GitLab, Bitbucket, Reddit, Stack Overflow, Discord, Notion, Obsidian, Jekyll, Hugo, Next.js, and thousands of other platforms natively.

---

Core Syntax Reference

Headings

Headings use hash symbols (#). The number of hashes determines the heading level, corresponding to HTML <h1> through <h6>.

# Heading 1 — Page title (use once per page)
## Heading 2 — Major section
### Heading 3 — Subsection
#### Heading 4 — Sub-subsection
##### Heading 5 — Rarely needed
###### Heading 6 — Almost never needed

Best practice: Use ## and ### for most content. Reserve # for the document title. Avoid skipping levels (going from ## to ####) as it breaks accessibility.

---

Paragraphs and Line Breaks

A blank line between text creates a new paragraph. A single newline within a paragraph is rendered as a space — the text flows together.

This is the first paragraph. It can be multiple
sentences on multiple lines — they render as one block.

This is the second paragraph, separated by a blank line.

To force a line break within a paragraph (HTML <br>),  
end the line with two trailing spaces before the newline.

---

Emphasis and Strong

*italic text* or _italic text_
**bold text** or __bold text__
***bold and italic*** or ___bold and italic___
~~strikethrough~~

Renders as: italic, bold, bold italic, strikethrough.

Note: Most style guides recommend using * consistently rather than mixing * and _, as underscore-based emphasis can conflict with variable names containing underscores in some contexts.

---

Lists

Unordered lists use -, *, or +:

- First item
- Second item
  - Nested item (indent with 2 spaces)
  - Another nested item
- Third item

Ordered lists use numbers followed by a period. The actual numbers do not matter — Markdown resets them sequentially:

1. First item
2. Second item
3. Third item

Or:

1. First item
1. Second item  ← Still renders as "2."
1. Third item   ← Still renders as "3."

Task lists (GitHub Flavored Markdown):

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

Renders as interactive checkboxes on GitHub and many other platforms.

---

Links and Images

[Link text](https://example.com)
[Link with title](https://example.com "Title appears on hover")

<!-- Reference-style links (cleaner for text-heavy documents) -->
[Link text][reference-id]
[reference-id]: https://example.com

<!-- Images: same syntax as links with ! prefix -->
![Alt text](https://example.com/image.jpg)
![Alt text](https://example.com/image.jpg "Optional title")

Alt text is not optional from an accessibility standpoint — screen readers use it, and it appears when an image fails to load. Make it descriptive.

---

Code

Inline code uses single backticks:

Use the `console.log()` function to debug output.

Code blocks use triple backticks with an optional language specifier for syntax highlighting:

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

```python
def greet(name):
    return f"Hello, {name}!"
```

```bash
npm install --save-dev webpack
```

The language specifier after the opening backticks (javascript, python, bash, css, sql, json, yaml, etc.) activates syntax highlighting in GitHub, documentation sites, and most Markdown editors.

---

Blockquotes

> This is a blockquote. It renders with a left border and indentation.
>
> Multiple paragraphs in a blockquote need a `>` on blank lines too.
>
> > Nested blockquotes work by adding another `>`.

---

Horizontal Rules

Three or more hyphens, asterisks, or underscores on their own line:

---
***
___

All produce a horizontal dividing line. Using --- is the most common convention.

---

Tables (GitHub Flavored Markdown)

| Column 1 | Column 2 | Column 3 |
|---|---|---|
| Row 1, Col 1 | Row 1, Col 2 | Row 1, Col 3 |
| Row 2, Col 1 | Row 2, Col 2 | Row 2, Col 3 |

<!-- Column alignment -->
| Left-aligned | Center-aligned | Right-aligned |
|:---|:---:|---:|
| Text | Text | Text |

The second row of hyphens is required and defines the header separator. Colon placement in that row controls alignment.

---

Escaping Characters

To display a character that Markdown would interpret as syntax, prefix it with a backslash:

\*This text has asterisks but is not italic\*
\# This is not a heading
\[This is not a link\]

---

Extended Syntax and Flavors

Standard Markdown (CommonMark) covers the basics. Several extended specifications add features used on specific platforms.

GitHub Flavored Markdown (GFM)

The most widely adopted extension, adding:

• Task lists (- [x])
• Tables
• Fenced code blocks with language specifiers
• Strikethrough (~~text~~)
• Automatic URL linking
• @mentions and #issue-number references in GitHub contexts

MDX

Markdown with JSX — allows React components to be embedded directly in Markdown files. Used in Next.js documentation sites, Docusaurus, and other React-based documentation systems.

import { Chart } from './Chart'

## Sales Data

Here is this quarter's breakdown:

<Chart data={salesData} type="bar" />

Regular Markdown continues after the component.

Frontmatter

YAML or TOML metadata at the top of a Markdown file, used by static site generators to define page title, date, category, slug, and other metadata:

---
title: "My Blog Post"
date: "2026-05-05"
category: "Developer"
author: "SimpleWebToolsBox Team"
---

## Article begins here

The --- delimiters indicate a YAML block. Static site generators (Jekyll, Hugo, Gatsby, Next.js with MDX) parse this metadata separately from the content.

---

Markdown in Different Environments

Understanding where Markdown runs and what flavor is supported avoids frustrating rendering surprises.

---

Common Mistakes

Forgetting blank lines around block elements. Headings, lists, code blocks, and blockquotes need blank lines before and after them to render correctly in some parsers.

Inconsistent list indentation. Different parsers treat list indentation differently. Use 2 spaces or 4 spaces consistently.

Unescaped underscores in technical writing. Variable names like my_variable_name can trigger italic rendering in some parsers. Wrap code in backticks: `my_variable_name`.

Using HTML when Markdown suffices. Markdown renders faster, is more portable, and easier to read as source. Reach for HTML only when Markdown genuinely cannot express what you need.

---

Previewing and Editing Markdown

SimpleWebToolsBox offers a free Markdown Editor and Preview tool that renders your Markdown in real time as you type. It supports GFM syntax including tables, task lists, and code highlighting. Useful for:

• Drafting README files before committing
• Previewing blog post formatting before publishing
• Checking how tables and code blocks render
• Learning syntax interactively by seeing instant feedback

---

Summary

• Markdown is a lightweight plain-text format that renders to HTML across virtually every writing and development platform.
• Core syntax covers headings, paragraphs, emphasis, lists, links, images, code, blockquotes, and tables.
• GitHub Flavored Markdown (GFM) is the most common extension, adding task lists, tables, and fenced code blocks.
• Frontmatter (YAML between --- delimiters) provides metadata for static site generators.
• MDX extends Markdown with React component support for documentation sites.
• Different platforms support different Markdown flavors — verify what your target environment supports.
• Preview Markdown in real time using the free editor on SimpleWebToolsBox.

---

Content Tracking Log