@vendys/markdownlint-config

0.1.1 • Public • Published

Markdown Style Guide

npm version

이 가이드는 벤디스에서 Markdown 또는 CommonMark로 문서를 작성할 때 기준이 되는 스타일을 설명한다.

노트: 이 가이드는 markdownlint를 사용한다고 가정한다.

Table of Contents

  1. 블록 요소(Block Elements)
    1. 문단(Paragraphs)과 줄 바꿈(Line Breaks)
    2. 제목(Headers)
    3. 인용 블록(Blockquotes)
    4. 목록(Lists)
    5. 코드 블록(Code Blocks)
    6. 수평선(Horizontal Rules)
  2. 스팬 요소(Span Elements)
    1. 링크(Links)
    2. 강조(Emphasis)
    3. 코드 스팬(Code Span)
    4. 이미지(Images)

블록 요소(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)

  • 6.1 수평선은 ---으로 표기한다. markdownlint: hr-style

    <!-- 잘못된 예 -->
    
    - - -
    
    ***
    
    * * *
    
    ****
    
    <!-- 올바른 예 -->
    
    ---

맨 위로

스팬 요소(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

    <!-- 잘못된 예 -->
    
    ![](image.jpg)
    
    <!-- 올바른 예 -->
    
    ![대체 텍스트](image.jpg)

맨 위로

Install

npm i @vendys/markdownlint-config

DownloadsWeekly Downloads

2

Version

0.1.1

License

CC-BY-4.0

Unpacked Size

25.3 kB

Total Files

4

Last publish

Collaborators

  • jgkim