Category Reference

Markdown

제목, 링크, 코드 블록, 표, 각주, 확장 문법까지 Markdown의 핵심 흐름을 카드형 레퍼런스로 정리합니다.

Search cards

40 cards

Search titles, summaries, tags, and subcategories.

기본 문법

6 cards

기본 문법

제목과 목록 기본

문서 구조를 빠르게 잡기 위한 제목과 목록의 기본 문법을 정리한 Markdown 입문 카드입니다.

# 제목 1
## 제목 2
### 제목 3

- bullet 항목
- bullet 항목

1. 번호 목록
2. 번호 목록

기본 문법

문단과 줄바꿈

문단을 나누는 빈 줄, 같은 문단 안 줄바꿈, hard break의 차이를 Markdown 기준으로 정리합니다.

첫 번째 문단입니다.

두 번째 문단입니다.
같은 문단에서 줄만 바꾸고 싶다면 끝에 공백 두 칸을 넣거나\
역슬래시를 씁니다.

기본 문법

강조와 취소선

기울임, 굵게, 굵은 기울임, 취소선을 Markdown과 GitHub 확장 기준으로 정리합니다.

*기울임*
굵게
*굵은 기울임*
취소선

기본 문법

ordered list 번호와 start

ordered list의 시작 번호, marker 형식, 문단 중간에서 목록이 시작될 때 깨지기 쉬운 조건을 정리합니다.

1. 첫 번째
2. 두 번째
3. 세 번째

기본 문법

들여쓰기 코드 블록

네 칸 들여쓰기로 만드는 indented code block과 fenced code block의 차이, 목록 안에서 필요한 추가 들여쓰기를 정리합니다.

npm run build
    npm run test

기본 문법

entity reference

Markdown에서 `&`, `|`, ```처럼 HTML entity와 numeric character reference를 써서 특수 문자를 안전하게 표시하는 기준을 정리합니다.

AT&amp;T
표 안의 pipe: <code>A&#124;B</code>
HTML 태그를 문자로 보기: &lt;div&gt;

구조화

5 cards

구조화

중첩 목록과 들여쓰기

목록 안에 하위 목록, 코드 블록, 문단을 넣을 때 중요한 들여쓰기 규칙을 정리합니다.

- 상위 항목
  - 하위 항목
  - 하위 항목

1. 단계
   1. 세부 단계
   2. 세부 단계

구조화

인용문과 구분선

설명 인용, 참고 메모, 섹션 전환에 자주 쓰는 blockquote와 thematic break를 정리합니다.

> 중요한 참고 문장
> 두 줄 이상도 가능합니다.

---

구조화

목차와 문서 outline 설계

Markdown heading으로 자동 목차와 문서 outline을 만들 때 heading 깊이, anchor 안정성, 중복 제목을 관리하는 기준입니다.

문서 outline 기준

1. H1은 문서 제목으로 1개만 둔다
2. 주요 장은 H2로 둔다
3. 세부 설명은 H3까지만 우선 사용한다
4. 같은 제목 반복을 피한다
5. 렌더러에서 자동 anchor를 확인한다

구조화

빈 줄과 block 경계

Markdown에서 빈 줄이 문단, 목록, 인용문, 코드 블록의 경계를 어떻게 바꾸는지와 portable 문서 작성 기준을 정리합니다.

문단 하나입니다.

문단 둘입니다.

- 목록
- 목록

구조화

문서 파일 구조

README, index 문서, docs 디렉터리, assets 폴더를 나누는 기준과 상대 링크가 깨지지 않게 유지하는 구조를 정리합니다.

repo/
├─ README.md
├─ CHANGELOG.md
├─ docs/
│  ├─ index.md
│  ├─ setup.md
│  └─ images/
│     └─ architecture.png
└─ src/

문서화

9 cards

문서화

코드 블록과 fence

삼중 backtick과 언어 지정으로 코드 예시를 깔끔하게 보여 주는 Markdown 코드 블록 기본 카드입니다.

```js
console.log("hello");
```

문서화

인라인 코드와 escaping

짧은 명령어를 표시하는 인라인 코드와 Markdown 기호를 문자 그대로 보여 주는 escaping 규칙을 정리합니다.

`git status`
\*별표\*를 문자 그대로 보여 주기
``code with `backtick` inside``

문서화

frontmatter 기본

Markdown 문서 상단에 YAML 메타데이터를 넣는 frontmatter의 구조, Markdown 표준과의 차이, 작성 시 주의할 점을 정리합니다.

---
title: 문서 제목
description: 짧은 설명
tags:
  - markdown
  - docs
published: true
---

문서화

linting과 formatting

Markdown 문서에서 lint와 format의 역할 차이, markdownlint와 Prettier를 함께 쓸 때의 기준, 자동화에서 주의할 점을 정리합니다.

npx prettier --write "docs//*.md"
npx markdownlint "docs//*.md"

문서화

MDX component와 expression

MDX에서 Markdown 본문과 JSX component, ESM import/export, 중괄호 expression이 만나는 경계와 작성 시 깨지기 쉬운 지점을 정리합니다.

import { Callout } from './components/Callout.jsx'

# 설치 가이드

일반 문장은 Markdown으로 작성합니다.

<Callout tone="warning">
  Node.js 버전을 먼저 확인하세요.
</Callout>

현재 버전: {version}

문서화

렌더링 파이프라인

Markdown이 HTML이나 React 컴포넌트로 바뀌는 과정에서 parser, AST, remark, rehype, sanitizer가 맡는 역할을 정리합니다.

Markdown source
  -> parse
  -> mdast
  -> remark plugins
  -> remark-rehype
  -> hast
  -> rehype plugins
  -> HTML / React components

문서화

이식성 체크리스트

GitHub, 정적 사이트, MDX, PDF 변환처럼 Markdown 문서가 다른 렌더러로 이동할 때 확인해야 할 문법과 렌더링 경계를 정리합니다.

Markdown 이동 전 점검

1. 대상 렌더러가 CommonMark, GFM, MDX 중 무엇을 지원하는지 확인
2. 표, task list, footnote, Mermaid, math 사용 여부 확인
3. raw HTML과 custom component 지원 여부 확인
4. heading anchor와 상대 링크를 실제 렌더링에서 확인
5. PDF/Word 변환이면 이미지, 표, 코드 블록을 별도 점검

문서화

include와 transclusion

Markdown에서 다른 파일을 끼워 넣는 include가 표준 문법이 아니라는 점과 MDX, 정적 사이트, GitHub 문서에서 갈리는 기준을 정리합니다.

자세한 설정은 [배포 가이드](./deploy.md)를 참고하세요.

문서화

GitHub issue와 PR template

GitHub 저장소에서 Markdown issue template과 pull request template을 어디에 두고, YAML issue form과 어떻게 구분해야 하는지 정리합니다.

repo/
├─ .github/
│  ├─ ISSUE_TEMPLATE/
│  │  ├─ bug_report.md
│  │  └─ feature_request.yml
│  └─ pull_request_template.md
└─ docs/
   └─ PULL_REQUEST_TEMPLATE/
      └─ release.md

링크와 참조

8 cards

링크와 참조

링크와 이미지 기본

텍스트 링크와 이미지를 문서 안에 자연스럽게 넣는 Markdown 기본 문법을 정리한 카드입니다.

[링크 텍스트](https://example.com)
[링크 텍스트](https://example.com "툴팁 텍스트")

![대체 텍스트](https://example.com/image.png)
![프로세스 상태도](./images/process-state.png)

링크와 참조

참조형 링크

같은 링크를 여러 번 쓰거나 본문을 깔끔하게 유지하고 싶을 때 유용한 참조형 링크 문법을 정리합니다.

[공식 문서][docs]
[API 문서][docs]

[docs]: https://example.com "선택적 툴팁"

링크와 참조

섹션 링크와 상대 경로 링크

같은 문서의 제목으로 이동하는 링크와 저장소 안 다른 파일로 이동하는 상대 경로 링크를 정리합니다.

[설치로 이동](#설치)
[상위 README](../README.md)
[설정 파일](./config/app.yml)

링크와 참조

link destination과 title

Markdown 링크에서 URL에 공백, 괄호, title이 섞일 때 깨지는 이유와 angle bracket, escaping, link title을 쓰는 기준을 정리합니다.

[기본 링크](https://example.com/docs)

[괄호가 있는 URL](<https://example.com/search?q=(markdown)>)

[title이 있는 링크](https://example.com "공식 문서")

[괄호 escape](foo\(bar\))

링크와 참조

이미지 alt와 상대 경로

Markdown 이미지 문법에서 alt text가 맡는 역할과 저장소 안 이미지를 상대 경로로 연결할 때의 기준을 정리합니다.

![검색 결과 화면](./images/search-results.png)

링크와 참조

링크 점검

Markdown 문서의 상대 링크, 섹션 링크, 외부 URL이 깨지는 지점을 찾고 자동 점검에 넣는 기준을 정리합니다.

Markdown 링크 점검 순서

1. 로컬 상대 경로가 실제 파일을 가리키는지 확인
2. 같은 문서의 #anchor가 렌더러에서 생성되는 값과 맞는지 확인
3. 외부 URL은 상태 코드와 redirect를 확인
4. 이미지 링크는 파일 존재, 대소문자, 배포 경로를 확인
5. CI에서는 내부 링크와 외부 링크를 다른 강도로 검사

링크와 참조

이미지 크기와 caption

Markdown 이미지에서 크기 조절과 caption이 표준 문법에 없다는 점을 기준으로 HTML, MDX, figure 사용 경계를 정리합니다.

![대시보드 화면](./images/dashboard.png)

링크와 참조

GitHub 첨부 파일과 Markdown 링크

GitHub issue, PR, discussion comment에 파일을 첨부할 때 생성되는 Markdown 링크와 접근 권한, 이미지 대체 텍스트 기준을 정리합니다.

1. issue, PR, discussion comment 입력창에 파일을 drag and drop
2. GitHub가 Markdown 링크나 이미지 문법을 삽입
3. alt text와 설명을 사람이 읽을 수 있게 수정
4. 공개 저장소라면 접근 권한과 민감 정보 여부 확인
5. 장기 문서라면 저장소 파일로 옮길지 판단

확장 문법과 GitHub

12 cards

확장 문법과 GitHub

표 기본

비교표와 요약표를 빠르게 만들 수 있는 Markdown 표 문법의 기본 패턴입니다.

| 항목 | 설명 |
| --- | --- |
| CPU | 계산 담당 |
| Memory | 데이터 임시 저장 |

확장 문법과 GitHub

표 정렬과 특수 문자 escaping

표 열 정렬, 셀 안의 pipe 문자, 짧은 코드 강조처럼 표를 안정적으로 쓰는 규칙을 정리합니다.

| Left  | Center | Right |
| :---- | :----: | ----: |
| 이름  |   a    |     1 |
| 경로  |   b    |    12 |
| 특수  |  A \| B |   100 |

확장 문법과 GitHub

details와 HTML 주석

접을 수 있는 섹션과 문서 내부 메모를 만들 때 쓰는 `<details>`, `<summary>`, HTML 주석 문법을 정리합니다.

<details>
  <summary>자세히 보기</summary>

  추가 설명을 이 안에 넣습니다.
</details>

<!-- 이 메모는 렌더링되지 않습니다. -->

확장 문법과 GitHub

자동 링크와 GitHub 참조

URL, 이슈 번호, 커밋 SHA 같은 문자열이 GitHub에서 자동 링크로 바뀌는 규칙을 정리합니다.

Visit https://github.com
#123
owner/repo#456
a5c3785ed3

확장 문법과 GitHub

체크리스트와 task list

체크박스 목록으로 할 일을 추적하는 GitHub task list 문법과 사용 맥락을 정리합니다.

- [ ] 로그인 화면 구현
- [x] API 응답 형식 정리
- [ ] 문서 업데이트

## 릴리스 준비
- [x] 버전 태그 정리
- [ ] 변경 로그 작성
- [ ] 배포 후 smoke test

확장 문법과 GitHub

각주

본문 흐름을 끊지 않고 출처나 부가 설명을 아래로 보내는 각주 문법을 GitHub 기준으로 정리합니다.

Markdown는 가볍고 읽기 쉬운 문법입니다.[^1]

[^1]: 자세한 배경 설명이나 출처를 적습니다.

확장 문법과 GitHub

알림 블록과 admonition

GitHub에서 메모, 경고, 팁을 구분해 보여 주는 alert block 문법을 정리합니다.

> [!NOTE]
> 이 문단은 참고 메모입니다.

> [!WARNING]
> 주의가 필요한 설정입니다.

> [!TIP]
> 명령 실행 전에 `.env.example`을 먼저 복사해 두면 설정 실수를 줄일 수 있습니다.

확장 문법과 GitHub

Mermaid 다이어그램

Markdown 코드 블록 안에서 Mermaid 다이어그램을 작성하는 방식, GitHub 렌더링 조건, 문서화에서 사용할 때의 경계를 정리합니다.

확장 문법과 GitHub

수식 표현

GitHub Markdown에서 inline 수식과 block 수식을 작성하는 방식, `$` 문자가 본문과 충돌할 때 피하는 방법을 정리합니다.

문장 안 수식은 $E = mc^2$처럼 작성합니다.

$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$

확장 문법과 GitHub

raw HTML과 sanitization

Markdown 안에 HTML을 직접 넣을 때 block HTML과 inline HTML이 어떻게 처리되고, GitHub 같은 렌더러에서 왜 일부 태그가 필터링되는지 정리합니다.

<details>
  <summary>자세히 보기</summary>

  Markdown 문단을 함께 쓸 수 있습니다.
</details>

문장 안에서는 <kbd>Ctrl</kbd> + <kbd>K</kbd>처럼 inline HTML을 쓸 수 있습니다.

확장 문법과 GitHub

CommonMark와 GFM 호환성

CommonMark와 GitHub Flavored Markdown의 관계, GFM 확장 문법, 다른 렌더러로 옮길 때 깨지기 쉬운 기능을 구분합니다.

CommonMark 중심 문법
- # Heading
- - List
- [Link](url)
-

확장 문법과 GitHub

GitHub closing keyword

GitHub issue와 pull request 본문에서 `Closes #10`, `Fixes owner/repo#20` 같은 keyword가 링크와 자동 종료로 이어지는 기준을 정리합니다.

Closes #10
Fixes owner/repo#20
Resolves https://github.com/owner/repo/issues/30

Duplicate of #42

Loading category cards

Preparing references and filters for this topic. 이 주제의 레퍼런스와 필터를 준비하고 있습니다.

문서 outline 기준 1. H1은 문서 제목으로 1개만 둔다 2. 주요 장은 H2로 둔다 3. 세부 설명은 H3까지만 우선 사용한다 4. 같은 제목 반복을 피한다 5. 렌더러에서 자동 anchor를 확인한다

import { Callout } from './components/Callout.jsx' # 설치 가이드 일반 문장은 Markdown으로 작성합니다. <Callout tone="warning"> Node.js 버전을 먼저 확인하세요. </Callout> 현재 버전: {version}

Markdown 이동 전 점검 1. 대상 렌더러가 CommonMark, GFM, MDX 중 무엇을 지원하는지 확인 2. 표, task list, footnote, Mermaid, math 사용 여부 확인 3. raw HTML과 custom component 지원 여부 확인 4. heading anchor와 상대 링크를 실제 렌더링에서 확인 5. PDF/Word 변환이면 이미지, 표, 코드 블록을 별도 점검

repo/ ├─ .github/ │ ├─ ISSUE_TEMPLATE/ │ │ ├─ bug_report.md │ │ └─ feature_request.yml │ └─ pull_request_template.md └─ docs/ └─ PULL_REQUEST_TEMPLATE/ └─ release.md

[링크 텍스트](https://example.com) [링크 텍스트](https://example.com "툴팁 텍스트") ![대체 텍스트](https://example.com/image.png) ![프로세스 상태도](./images/process-state.png)

[기본 링크](https://example.com/docs) [괄호가 있는 URL](<https://example.com/search?q=(markdown)>) [title이 있는 링크](https://example.com "공식 문서") [괄호 escape](foo$bar$)

Markdown 링크 점검 순서 1. 로컬 상대 경로가 실제 파일을 가리키는지 확인 2. 같은 문서의 #anchor가 렌더러에서 생성되는 값과 맞는지 확인 3. 외부 URL은 상태 코드와 redirect를 확인 4. 이미지 링크는 파일 존재, 대소문자, 배포 경로를 확인 5. CI에서는 내부 링크와 외부 링크를 다른 강도로 검사

1. issue, PR, discussion comment 입력창에 파일을 drag and drop 2. GitHub가 Markdown 링크나 이미지 문법을 삽입 3. alt text와 설명을 사람이 읽을 수 있게 수정 4. 공개 저장소라면 접근 권한과 민감 정보 여부 확인 5. 장기 문서라면 저장소 파일로 옮길지 판단

> [!NOTE] > 이 문단은 참고 메모입니다. > [!WARNING] > 주의가 필요한 설정입니다. > [!TIP] > 명령 실행 전에 `.env.example`을 먼저 복사해 두면 설정 실수를 줄일 수 있습니다.

<details> <summary>자세히 보기</summary> Markdown 문단을 함께 쓸 수 있습니다. </details> 문장 안에서는 <kbd>Ctrl</kbd> + <kbd>K</kbd>처럼 inline HTML을 쓸 수 있습니다.