Markdown Style Guide
이 가이드는 벤디스에서 Markdown 또는 CommonMark로 문서를 작성할 때 기준이 되는 스타일을 설명한다.
노트: 이 가이드는 markdownlint를 사용한다고 가정한다.
Table of Contents
블록 요소(Block Elements)
문단(Paragraphs)과 줄 바꿈(Line Breaks)
-
1.1 두 개의 스페이스를 이용해 줄 바꿈하는 경우를 제외하고, 줄 끝에 스페이스를 사용하지 않는다. markdownlint:
no-trailing-spaces<!-- 잘못된 예 --> 스페이스로 끝나는 줄⎵ <!-- 올바른 예 --> 줄 바꿈하기 위해 두 개의 스페이스를 사용한 줄⎵⎵ 끝에 스페이스를 사용하지 않은 줄
-
1.2 스페이스 대신 탭(tab)을 사용하지 않는다. markdownlint:
no-hard-tabs<!-- 잘못된 예 --> 문단 내용 ⇥* 목록을 들여쓰기 위해 탭을 사용 <!-- 올바른 예 --> 문단 내용 ⎵⎵* 목록을 들여쓰기 위해 스페이스를 사용
-
1.3 두 줄 이상 연속해 빈 줄을 사용하지 않는다. 단, 코드 블록은 예외로 한다. markdownlint:
no-multiple-blanks<!-- 잘못된 예 --> 문단 내용 ↵ ↵ 또 다른 문단 내용 <!-- 올바른 예 --> 문단 내용 ↵ 또 다른 문단 내용
제목(Header)
-
2.1 제목의 수준은 한 번에 한 단계씩 증가한다. markdownlint:
header-increment<!-- 잘못된 예 --> # 제목 1 ### 제목 3 두 번째 단계의 제목을 건너 뛰었다. <!-- 올바른 예 --> # 제목 1 ## 제목 2 ### 제목 3 #### 제목 4 ## 또 다른 제목 2 ### 또 다른 제목 3
-
2.2 문서의 첫 번째 제목은 최상위 수준으로 작성한다. markdownlint:
first-header-h1
단, 최상위 수준의 제목이 존재하는 문서의 일부로 Markdown이 사용될 때는 예외로 한다.<!-- 잘못된 예 --> ## H1 제목이 아님 ### 또 다른 제목 <!-- 올바른 예 --> # H1 제목으로 시작 ## 이후 하위 섹션에 H2 제목을 사용
-
2.3 제목은
#으로 시작하는 Atx 스타일을 따른다. markdownlint:header-style<!-- 잘못된 예 --> # ATX 스타일 H1 ## 닫힌 ATX 스타일 H2 ## Setext 스타일 H1 ================ <!-- 올바른 예 --> # ATX 스타일 H1 ## ATX 스타일 H2
-
2.4 Atx 스타일 제목의
#뒤에 스페이스를 사용한다. markdownlint:no-missing-space-atx<!-- 잘못된 예 --> #제목 1 ##제목 2 <!-- 올바른 예 --> # 제목 1 ## 제목 2
-
2.5 Atx 스타일 제목의
#뒤에 여러 개의 스페이스를 사용하지 않는다. markdownlint:no-multiple-space-atx<!-- 잘못된 예 --> #⎵⎵제목 1 ##⎵⎵제목 2 <!-- 올바른 예 --> #⎵제목 1 ##⎵제목 2
-
2.6 제목 앞뒤에 빈 줄을 사용한다. markdownlint:
blanks-around-headers
단, 제목 앞에 HTML 앵커가 존재할 수 있어 markdownlint의 규칙을 적용할 수 없다.<!-- 잘못된 예 --> # 제목 1 문단 내용 ↵ 또 다른 문단 내용 ## 제목 2 <!-- 올바른 예 --> # 제목 1 ↵ 문단 내용 ↵ 또 다른 문단 내용 ↵ ## 제목 2
-
2.7 제목은 들여쓰기 없이 시작해야 한다. markdownlint:
header-start-left<!-- 잘못된 예 --> 문단 내용 # 들여쓴 제목 <!-- 올바른 예 --> 문단 내용 # 제목
-
2.8 모든 제목의 내용은 서로 달라야 한다. markdownlint:
no-duplicate-header<!-- 잘못된 예 --> # 제목 내용 ## 제목 내용 <!-- 올바른 예 --> # 제목 내용 ## 또 다른 제목 내용
-
2.9 최상위 수준의 제목은 문서에 단 한 개만 존재한다. markdownlint:
single-h1<!-- 잘못된 예 --> # 최상위 수준의 제목 # 또 다른 최상위 수준의 제목 <!-- 올바른 예 --> # 문서 제목 ## 제목 ## 또 다른 제목
-
2.10 제목은
.,,,;,:등의 구두점으로 끝내지 않는다. markdownlint:no-trailing-punctuation<!-- 잘못된 예 --> # 이 것은 제목이다. <!-- 올바른 예 --> # 이 것은 제목이다
인용 블록(Blockquotes)
-
3.1 인용 블록을 나타내는 기호
>뒤에는 한 개의 스페이스를 사용해야 한다. markdownlint:no-multiple-space-blockquote<!-- 잘못된 예 --> >⎵⎵잘못된 들여쓰기를 한 인용 블록 >⎵⎵인용 블록을 나타내는 기호 뒤에는 한 개의 스페이스만 사용 <!-- 올바른 예 --> >⎵올바른 들여쓰기를 한 >⎵인용 블록
목록(List)
-
4.1 순서 없는 목록은
*,+,-의 순서로 작성한다. markdownlint:ul-style<!-- 잘못된 예 --> - 항목 1 * 항목 2 + 항목 3 * 항목 4 + 항목 5 <!-- 올바른 예 --> * 항목 1 + 항목 2 - 항목 3 + 항목 4 * 항목 4 + 항목 5
-
4.2 목록에서 같은 수준의 항목은 같은 크기로 들여쓴다. markdownlint:
list-indent<!-- 잘못된 예 --> * 항목 1 * 중첩된 항목 1 * 중첩된 항목 2 * 잘못 정렬된 항목 <!-- 올바른 예 --> * 항목 1 * 중첩된 항목 1 * 중첩된 항목 2 * 중첩된 항목 3
-
4.3 순서 없는 목록의 들여쓰기는 상위 수준 항목과 정렬될 수 있도록 두 개의 스페이스로 한다. markdownlint:
ul-indent<!-- 잘못된 예 --> * 항목 * 세 개의 스페이스로 들여쓴 항목 <!-- 올바른 예 --> * 항목 * 두 개의 스페이스로 들여쓴 항목
-
4.4 순서 있는 목록의 항목은 순서와 상관없이 모두
1.로 표기한다. markdownlint:ol-prefix<!-- 잘못된 예 --> 1. 항목 1 2. 항목 2 3. 항목 3 <!-- 올바른 예 --> 1. 항목 1 1. 항목 2 1. 항목 3
-
4.5
-,*,+,1.등 목록의 항목을 나타내는 기호 뒤에는 한 개의 스페이스를 사용해야 한다. markdownlint:list-marker-space<!-- 잘못된 예 --> *⎵⎵항목 1 *⎵⎵항목 2 1.⎵⎵항목 3 *⎵⎵항목 4 2.⎵⎵항목 5 <!-- 올바른 예 --> *⎵항목 1 *⎵항목 2 1.⎵항목 3 *⎵항목 4 2.⎵항목 5
-
4.6 목록 앞뒤에 빈 줄을 사용한다. markdownlint:
blanks-around-lists
단, 목록 앞에 HTML 앵커가 존재할 수 있어 markdownlint의 규칙을 적용할 수 없다.<!-- 잘못된 예 --> 문단 내용 * 항목 * 또 다른 항목 1. 항목 1. 또 다른 항목 문단 내용 <!-- 올바른 예 --> 문단 내용 * 항목 * 또 다른 항목 1. 항목 1. 또 다른 항목 문단 내용
코드 블록(Code Blocks)
-
5.1 코드 블록 앞뒤에 빈 줄을 사용한다. markdownlint:
blanks-around-fences<!-- 잘못된 예 --> 문단 내용 ``` 코드 블록 ``` ↵ ``` 또 다른 코드 블록 ``` 또 다른 문단 내용 <!-- 올바른 예 --> 문단 내용 ↵ ``` 코드 블록 ``` ↵ ``` 또 다른 코드 블록 ``` ↵ 또 다른 문단 내용
-
5.2 코드 블록을 사용할 때는 포함된 코드의 언어를 명시한다. markdownlint:
fenced-code-language<!-- 잘못된 예 --> ``` #!/bin/bash echo Hello world ``` <!-- 올바른 예 --> ```bash #!/bin/bash echo Hello world ```
수평선(Horizontal Rules)
스팬 요소(Span Elements)
링크(Links)
-
7.1 Markdown의 링크 문법을 반대로 쓸 수 없다. markdownlint:
no-reversed-links<!-- 잘못된 예 --> (잘못된 링크 문법)[http://www.example.com/] <!-- 올바른 예 --> [올바른 링크 문법](http://www.example.com/)
-
7.2 URL은 코드 스팬 없이 본문에 포함할 수 없고, 링크로 변경하고 싶은 경우에는 코드 스팬 대신
<와>로 URL을 감싼다. markdownlint:no-bare-urls<!-- 잘못된 예 --> 더 자세한 내용은 다음 URL을 참조하라. http://www.example.com/ <!-- 올바른 예 --> 더 자세한 내용은 다음 URL을 참조하라. <http://www.example.com/>
-
7.3 링크를 삽입할 때 링크 텍스트를 나타내는 기호
[의 뒤 또는]의 앞에는 스페이스를 사용하지 않는다. markdownlint:no-space-in-links<!-- 잘못된 예 --> [ 참고 링크 ](http://www.example.com/) <!-- 올바른 예 --> [참고 링크](http://www.example.com/)
-
7.3 연결된 대상이 없는 빈 링크는 사용하지 않는다. markdownlint:
no-empty-links<!-- 잘못된 예 --> [빈 링크]() [빈 프래그먼트](#) <!-- 올바른 예 --> [유효한 링크](https://example.com/) [유효한 프래그먼트](#fragment)
강조(Emphasis)
-
8.1
**,*,__,_등 볼드 또는 이탤릭 등 강조를 위한 기호 사이에 스페이스를 사용하지 않는다. markdownlint:no-space-in-emphasis<!-- 잘못된 예 --> ** 볼드로 ** 강조된 텍스트 * 이탤릭으로 * 강조된 텍스트 __ 볼드로 __ 강조된 텍스트 _ 이탤릭으로 _ 강조된 텍스트 <!-- 올바른 예 --> **볼드로** 강조된 텍스트 *이탤릭으로* 강조된 텍스트 __볼드로__ 강조된 텍스트 _이탤릭으로_ 강조된 텍스트
코드 스팬(Code Span)
-
9.1 코드 스팬에 사용하는 ````` 기호 사이에 스페이스를 사용하지 않는다. markdownlint:
no-space-in-code<!-- 잘못된 예 --> ` 코드 ` `코드 ` ` 코드` <!-- 올바른 예 --> `코드`
이미지(Images)
-
10.1 이미지를 삽입하는 경우 이를 대체하기 위한 텍스트를 함께 명시한다. markdownlint:
no-alt-text<!-- 잘못된 예 -->  <!-- 올바른 예 --> 