Markdown Syntax: A Complete Guide for Developers and Writers

What is Markdown?

Markdown is a lightweight markup language created by John Gruber in 2004, with significant contributions from Aaron Swartz. Its original purpose was simple yet ambitious: provide a way to write structured, formatted content using plain text that is both easy to read in its raw form and easy to convert into valid HTML. Unlike HTML, which surrounds content with verbose tags like <strong>bold</strong>, Markdown uses intuitive symbols — like **bold** — that feel natural even to non-technical readers.

Since its creation, Markdown has become one of the most widely adopted writing formats in the technology world. Its influence extends far beyond personal blogs. Today, Markdown is the default writing language on GitHub (README files, issues, pull requests, and comments), GitLab, Bitbucket, Reddit, Stack Overflow, Discord, Slack, Notion, Obsidian, Joplin, and countless documentation systems. Static site generators like Hugo, Jekyll, Gatsby, and Astro rely on Markdown files as their primary content source. Even book authors and academic researchers use Markdown with tools like Pandoc to produce PDFs, EPUB files, and LaTeX documents.

The beauty of Markdown lies in its portability and simplicity. A Markdown file is just a plain text file — typically with a .md or .markdown extension. It can be opened, read, and edited in any text editor, on any operating system, without any special software. There is no vendor lock-in, no proprietary format, and no risk of the file becoming unreadable in the future. This makes Markdown an ideal format for long-lived content like documentation, notes, and technical writing.

Headings and Paragraphs

Headings are the backbone of any well-structured document. In Markdown, headings are created using the hash symbol (#). The number of hash symbols determines the heading level, from 1 (the largest) to 6 (the smallest). Always include a space between the hash symbols and the heading text.

# 제목 레벨 1 (H1) — 문서 제목에 사용
## 제목 레벨 2 (H2) — 주요 섹션
### 제목 레벨 3 (H3) — 하위 섹션
#### 제목 레벨 4 (H4) — 세부 항목
##### 제목 레벨 5 (H5) — 드물게 사용
###### 제목 레벨 6 (H6) — 가장 작은 제목

Best practice: use only one H1 per document (for the document title), and structure the rest of your content with H2 through H4. Deeply nested heading levels (H5, H6) are rarely needed and may indicate that your document should be split into multiple files.

Paragraphs and Line Breaks

Paragraphs in Markdown are simply blocks of text separated by one or more blank lines. There is no special syntax needed — just write your text and leave an empty line between paragraphs.

이것은 첫 번째 단락입니다. 여러 문장을 이어서 쓸 수 있습니다.
같은 줄에 계속 작성하면 같은 단락으로 처리됩니다.

이것은 두 번째 단락입니다. 빈 줄로 구분됩니다.

줄바꿈을 하려면 줄 끝에 공백 두 개를 추가하거나
<br> 태그를 사용할 수 있습니다.

A common mistake is pressing Enter once and expecting a new line. In standard Markdown, a single line break within a paragraph is treated as a space. To force a line break without starting a new paragraph, add two or more spaces at the end of a line, or use an HTML <br> tag. Some Markdown variants (like GitHub Flavored Markdown) treat single line breaks as actual line breaks, which can cause confusion when switching between platforms.

Horizontal Rules

You can create a horizontal rule (a visual divider) using three or more hyphens, asterisks, or underscores on a line by themselves:

---
***
___

// 위 세 가지 모두 동일한 수평선을 생성합니다

Text Formatting

Markdown provides a clean, intuitive syntax for common text formatting. These inline formatting options can be combined and nested to create richly formatted content without cluttering your source text.

Bold and Italic

// 굵게 (Bold) — 별표 두 개 또는 밑줄 두 개
**굵은 텍스트**
__이것도 굵은 텍스트__

// 기울임 (Italic) — 별표 하나 또는 밑줄 하나
*기울임 텍스트*
_이것도 기울임 텍스트_

// 굵은 기울임 (Bold + Italic) — 별표 세 개
***굵은 기울임 텍스트***
___이것도 굵은 기울임___

Convention tip: most style guides recommend using **asterisks** for bold and *asterisks* for italic, rather than underscores. Underscores can cause unexpected behavior in the middle of words (e.g., some_variable_name may be partially italicized in some parsers).

Strikethrough, Inline Code, and Blockquotes

// 취소선 (Strikethrough) — 물결표 두 개 (GFM 확장)
~~삭제된 텍스트~~

// 인라인 코드 (Inline Code) — 백틱 하나
변수 `userName`을 사용하세요.
`npm install` 명령어를 실행하세요.

// 백틱을 포함하는 인라인 코드 — 백틱 두 개로 감싸기
``이 안에서는 `백틱`을 사용할 수 있습니다``

// 인용문 (Blockquote) — > 기호
> 이것은 인용문입니다.
> 여러 줄에 걸쳐 작성할 수 있습니다.
>
> > 중첩된 인용문도 가능합니다.

// 하이라이트 (일부 파서 지원)
==하이라이트된 텍스트==

Blockquotes are especially useful for quoting external sources, highlighting important notes, or creating callout boxes. On GitHub, you can combine blockquotes with special keywords to create alerts:

// GitHub Alerts (GitHub 전용 확장)
> [!NOTE]
> 참고할 정보를 작성합니다.

> [!TIP]
> 유용한 팁을 제공합니다.

> [!WARNING]
> 주의가 필요한 내용을 알립니다.

> [!CAUTION]
> 심각한 위험을 경고합니다.

Lists

Lists are one of the most frequently used Markdown elements. Markdown supports ordered (numbered) lists, unordered (bulleted) lists, nested lists, and task lists (checkboxes).

Unordered Lists

// 순서 없는 목록 — 하이픈(-), 별표(*), 또는 플러스(+) 사용
- 첫 번째 항목
- 두 번째 항목
- 세 번째 항목

* 별표로도 작성 가능
* 또 다른 항목

+ 플러스 기호도 사용 가능
+ 또 다른 항목

Ordered Lists

// 순서 있는 목록 — 숫자 + 마침표
1. 첫 번째 단계
2. 두 번째 단계
3. 세 번째 단계

// 실제 번호는 상관없음 — Markdown이 자동 번호 매김
1. 첫 번째
1. 두 번째 (1로 써도 2로 렌더링됨)
1. 세 번째 (1로 써도 3으로 렌더링됨)

// 시작 번호는 첫 번째 숫자를 따름
5. 이 목록은 5부터 시작
6. 6번
7. 7번

Nested Lists and Task Lists

// 중첩 목록 — 2~4칸 들여쓰기
- 메인 항목 1
  - 하위 항목 A
  - 하위 항목 B
    - 더 깊은 중첩
- 메인 항목 2

// 순서 있는 목록 + 순서 없는 목록 혼합
1. 첫 번째 단계
   - 세부 사항 A
   - 세부 사항 B
2. 두 번째 단계
   - 세부 사항 C

// 체크박스 (Task Lists) — GFM 확장
- [x] 완료된 작업
- [x] 이것도 완료
- [ ] 아직 미완료
- [ ] 이것도 미완료

Task lists are a GitHub Flavored Markdown (GFM) extension that renders interactive checkboxes in GitHub issues and pull requests. They are incredibly useful for tracking progress on multi-step tasks, code review checklists, and project planning. Many note-taking apps like Obsidian and Notion also support this syntax.

Links and Images

Links and images share a similar syntax in Markdown, which makes them easy to remember once you learn one. The core pattern is square brackets for the display text followed by parentheses for the URL.

Links

// 인라인 링크 — [표시 텍스트](URL)
[Google](https://www.google.com)
[BeautiCode](https://beauticode.app)

// 제목 속성 포함 링크
[Google](https://www.google.com "구글 홈페이지")

// 자동 링크 — URL을 꺾쇠괄호로 감싸기
<https://www.google.com>
<user@example.com>

// 참조 링크 — 문서 하단에 URL을 모아서 정의
[Markdown 공식 사이트][markdown-site]
[GitHub][gh]

// 문서 하단에 참조 정의
[markdown-site]: https://daringfireball.net/projects/markdown/
[gh]: https://github.com "GitHub 홈페이지"

// 참조 링크는 숫자로도 사용 가능
[링크 텍스트][1]
[1]: https://example.com

Reference-style links are particularly useful in long documents where the same URL is used multiple times, or when you want to keep your source text clean and readable. All the URLs are collected at the bottom of the file, making them easy to update.

Images

// 인라인 이미지 — ![대체 텍스트](이미지 URL)
![로고](https://example.com/logo.png)

// 제목 속성 포함 이미지
![로고](https://example.com/logo.png "회사 로고")

// 참조 스타일 이미지
![대체 텍스트][logo-img]
[logo-img]: https://example.com/logo.png

// 이미지에 링크 걸기 — 이미지를 링크 텍스트 위치에 넣기
[![대체 텍스트](image.png)](https://example.com)

// HTML로 이미지 크기 조절 (Markdown에서는 크기 지정 불가)
<img src="image.png" alt="설명" width="300">

Standard Markdown does not support image resizing, alignment, or captions. For these features, you need to use raw HTML within your Markdown file. Most Markdown renderers allow HTML tags to be mixed freely with Markdown content.

Code Blocks

Code blocks are essential for technical writing. Markdown offers two types: inline code (for short snippets within a sentence) and fenced code blocks (for multi-line code examples). Fenced code blocks support syntax highlighting when you specify the language.

Fenced Code Blocks with Syntax Highlighting

// 기본 코드 블록 — 백틱 세 개로 감싸기
```
일반 코드 블록 (언어 미지정)
```

// 언어 지정으로 구문 강조 활성화
```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

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

```sql
SELECT users.name, COUNT(orders.id) AS order_count
FROM users
LEFT JOIN orders ON users.id = orders.user_id
GROUP BY users.name
HAVING order_count > 5;
```

Most Markdown renderers support hundreds of languages for syntax highlighting, including javascript, typescript, python, java, go, rust, sql, bash, json, yaml, css, and html.

Diff Code Blocks

Diff code blocks are particularly useful for code reviews, changelogs, and documentation that explains modifications to existing code:

// diff 언어를 지정하면 추가/삭제 라인이 색상으로 구분됨
```diff
- const oldVariable = "이전 값";
+ const newVariable = "새로운 값";

  function unchanged() {
-   return false;
+   return true;
  }
```

Tables

Markdown tables use pipes (|) and hyphens (-) to define columns and rows. While the syntax can feel tedious for large tables, it produces clean, readable results in most renderers. Tables are a GFM extension — not part of the original Markdown specification — but they are supported virtually everywhere today.

Basic Table Syntax

// 기본 테이블 — 파이프(|)와 하이픈(-)으로 구성
| 이름     | 나이 | 도시     |
|----------|------|----------|
| Alice    | 30   | New York |
| Bob      | 25   | London   |
| Charlie  | 35   | Tokyo    |

Column Alignment

// 열 정렬 — 콜론(:) 위치로 지정
| 왼쪽 정렬   | 가운데 정렬  | 오른쪽 정렬 |
|:------------|:----------:|------------:|
| Left        |   Center   |        Right |
| aligned     |  aligned   |      aligned |
| text        |    text    |         text |

// :--- = 왼쪽 정렬 (기본값)
// :--: = 가운데 정렬
// ---: = 오른쪽 정렬

Tips for Complex Tables

Markdown tables have limitations: they do not support merged cells (colspan/rowspan), multi-line content within a cell, or complex formatting. Here are some practical tips for working with tables:

• Keep tables simple. If your table needs merged cells or complex layouts, use HTML tables instead — they work inside Markdown files.
• Columns do not need to be perfectly aligned in your source text. The renderer will handle alignment. But aligning them improves readability of the raw Markdown.
• Use inline formatting inside table cells: **bold**, `code`, and [links](url) all work inside cells.
• Generate tables programmatically. Writing large tables by hand is error-prone. Use a CSV to Markdown converter to transform spreadsheet data into Markdown table syntax instantly.

Advanced Markdown

Beyond the basics, many Markdown processors support extended syntax features. These vary by platform, so check your renderer's documentation to confirm support.

Footnotes

// 각주 — 본문에 참조 표시, 문서 하단에 내용 정의
Markdown은 John Gruber가 만들었습니다[^1].
Aaron Swartz도 공헌했습니다[^2].

[^1]: John Gruber는 Daring Fireball 블로그를 운영합니다.
[^2]: Aaron Swartz는 RSS, Creative Commons 등에 기여한 인터넷 활동가입니다.

Definition Lists

// 정의 목록 — 일부 Markdown 파서 지원 (PHP Markdown Extra, Pandoc 등)
Markdown
: 경량 마크업 언어로, 일반 텍스트를 서식 있는 문서로 변환합니다.

HTML
: HyperText Markup Language의 약자로, 웹 페이지의 구조를 정의합니다.

Collapsible Sections (Details/Summary)

// 접기/펼치기 — HTML <details> 태그 사용 (GitHub 등에서 지원)
<details>
<summary>클릭하면 펼쳐집니다</summary>

숨겨진 내용이 여기에 표시됩니다.

- 목록도 사용 가능
- Markdown 문법도 사용 가능

```javascript
// 코드 블록도 포함 가능
const hidden = true;
```

</details>

Collapsible sections are especially useful in GitHub READMEs, issue templates, and long documents where you want to keep the page compact while still providing detailed information for readers who need it.

Math Equations (LaTeX)

// 인라인 수학식 — 달러 기호 하나
에너지 공식은 $E = mc^2$ 입니다.

// 블록 수학식 — 달러 기호 두 개
$$
\sum_{i=1}^{n} x_i = x_1 + x_2 + \cdots + x_n
$$

$$
f(x) = \int_{-\infty}^{\infty} \hat{f}(\xi) e^{2\pi i \xi x} d\xi
$$

// GitHub, GitLab, Notion, Obsidian, Jupyter 등에서 지원

Diagrams with Mermaid

// Mermaid 다이어그램 — GitHub, GitLab, Notion 등에서 지원
```mermaid
graph TD
    A[시작] --> B{조건 확인}
    B -->|참| C[작업 실행]
    B -->|거짓| D[종료]
    C --> D
```

// 시퀀스 다이어그램
```mermaid
sequenceDiagram
    Client->>Server: HTTP 요청
    Server->>Database: 쿼리 실행
    Database-->>Server: 결과 반환
    Server-->>Client: HTTP 응답
```

// Gantt 차트, Pie 차트, ERD 등도 지원

Mermaid is a powerful text-based diagramming tool that integrates naturally with Markdown. GitHub natively renders Mermaid diagrams in README files, issues, and pull requests since 2022. This eliminates the need to create, export, and maintain separate image files for flowcharts, sequence diagrams, and entity-relationship diagrams.

Preview Markdown with BeautiCode

Writing Markdown is only half the equation — you also need to see how it renders. Whether you are drafting a GitHub README, writing documentation, or composing a blog post, previewing your Markdown in real time helps you catch formatting errors, verify that links work, and ensure that your content looks exactly the way you intend.

BeautiCode offers a suite of Markdown tools that run entirely in your browser — no data is ever sent to a server:

• Markdown Preview — Paste or type your Markdown and see a beautiful, live-rendered preview instantly. Perfect for testing headings, lists, tables, code blocks, and all the syntax covered in this guide.
• JSON to Markdown — Convert JSON data into clean Markdown tables or formatted documents automatically. Ideal for turning API responses into readable documentation.
• CSV to Markdown — Transform CSV or spreadsheet data into perfectly formatted Markdown tables with proper alignment. Never hand-write a pipe table again.
• Text Statistics — Analyze your Markdown content for word count, character count, reading time, and more. Essential for blog posts and documentation with length requirements.

All processing happens client-side in your browser. Your content never leaves your machine, making these tools safe for private documentation and sensitive content.

Frequently Asked Questions

What is the difference between Markdown and HTML?

Markdown is a lightweight writing format designed for readability in its raw form. HTML is a full-featured markup language designed for web browsers. Markdown covers common formatting needs (headings, bold, lists, links, images, code) with minimal syntax, while HTML provides complete control over document structure, styling, and interactivity. Markdown is always converted to HTML before being displayed in a browser. The key advantage of Markdown is that the source text remains clean and human-readable, whereas HTML source is cluttered with tags. For most documentation and content writing, Markdown is sufficient. When you need features Markdown does not support (like custom styling, forms, or interactive elements), you can embed raw HTML directly in a Markdown file.

What is GitHub Flavored Markdown (GFM)?

GitHub Flavored Markdown (GFM) is GitHub's extended version of Markdown, built on top of the CommonMark specification. GFM adds several features not found in the original Markdown: tables (pipe syntax), task lists (checkboxes), strikethrough (~~text~~), autolinked URLs, fenced code blocks with syntax highlighting, alerts ([!NOTE], [!WARNING]), and Mermaid diagramrendering. GFM also handles line breaks differently — a single newline creates a line break, unlike standard Markdown where you need two spaces at the end of a line. GFM is the de facto standard for developer documentation because of GitHub's dominance in the open-source ecosystem.

Can I use Markdown for professional documentation?

Absolutely. Markdown is the standard for professional documentation in the software industry. Major projects like React, Vue.js, Kubernetes, Rust, and Python all use Markdown for their official documentation. Documentation platforms like Read the Docs, Docusaurus, MkDocs, and GitBook are built around Markdown files. For non-technical documentation (books, academic papers, reports), tools like Pandoc can convert Markdown to PDF, Word (DOCX), LaTeX, EPUB, and dozens of other formats. Many organizations use Markdown combined with Git version control for documentation-as-code workflows, enabling collaboration, code review, and change tracking for their documentation just like they do for source code.

How do I create a table of contents in Markdown?

Markdown does not have a built-in table of contents feature, but there are several ways to create one. The most common approach is to manually link to headings using anchor links. Most Markdown renderers automatically generate anchor IDs from heading text (e.g., ## Getting Started becomes #getting-started). You can then create a linked list at the top of your document: - [Getting Started](#getting-started). Many documentation tools (Docusaurus, MkDocs, GitBook) generate tables of contents automatically from your heading structure. VS Code extensions like "Markdown All in One" can also generate and update a table of contents automatically.

Which Markdown editor should I use?

The best Markdown editor depends on your workflow. VS Codewith the "Markdown All in One" extension is the most popular choice for developers — it offers live preview, keyboard shortcuts, auto-completion, and linting. Obsidian is excellent for personal knowledge management with its bidirectional linking and graph view. Typora provides a seamless WYSIWYG experience where you see the formatted output as you type. StackEdit and Dillinger are browser-based editors for quick editing without installing anything. For quick previewing and testing, you can use BeautiCode's Markdown Preview tool — paste your Markdown and see the rendered output instantly, right in your browser.