@naverpay/markdown-lint

markdown 파일 검사용 lint 도구입니다.
DavidAnson/markdownlint에서 제공하는 패키지와 규칙을 사용하고 있으며, 몇 가지 rule은 커스텀 되어 있습니다.

Installation

npm i @naverpay/markdown-lint -D

Config

@naverpay/markdown-lint를 설치하면 postinstall을 통해 자동으로 .markdownlint.json이 생성됩니다.
이미 .markdownlint.json이 존재한다면 생성되지 않습니다.

markdown-lint config는 jsonc 형식으로 작성되어 있어, 주석을 통해 rule에 대한 설명을 확인할 수 있습니다.
각 규칙의 명세는 여기서 확인할 수 있습니다.

Integrating with IDE

1. IDE에 markdownlint extension for vscode를 설치합니다.
2. 저장시 lint가 동작할 수 있도록 setting.json에 설정을 추가합니다.

{
    "editor.codeActionsOnSave": {
        "source.fixAll.markdownlint": true
    }
}

IDE에서 오류 표기를 하고 싶지 않은 파일이 있다면 .markdownlintignore를 추가합니다.

// .markdownlintignore
CHANGELOG.md

CLI

package.json에 스크립트를 추가하여 CLI 환경에서 사용할 수 있습니다.

{
    "scripts": {
        "markdownlint": "markdownlint '**/*.md'",
        "markdownlint:fix": "markdownlint --fix '**/*.md'",
    },
}

기본으로 루트에 있는 config 파일을 읽습니다. (.markdownlint.jsonc/json/yaml/yml/cjs/mjs)
그 외 위치에 config 파일을 둔다면 --config 인수로 정의해주어야 합니다.

{
    "scripts": {
        "markdownlint": "markdownlint --config 'config/.markdownlint.jsonc' '**/*.md'",
        "markdownlint:fix": "markdownlint --config 'config/.markdownlint.jsonc' --fix '**/*.md'",
    },
}

무시하고 싶은 파일이나 폴더가 있다면 #을 붙여 ignore 할 수 있습니다.
(node_modules 폴더는 자동으로 무시됩니다.)

{
    "scripts": {
        "markdownlint": "markdownlint '**/*.md' '#**/CHANGELOG.md'",
        "markdownlint:fix": "markdownlint --fix '**/*.md' '#**/CHANGELOG.md'",
    },
}

이외 옵션은 여기서 확인할 수 있습니다.

Conflict with prettier

prettier와 markdown-lint를 함께 사용한다면 몇 가지 rule에서 충돌이 발생할 수 있습니다.
충돌하는 rule은 여기서 확인할 수 있습니다.
해당 rule에 false 값을 주어 끄거나, .prettierignore에 마크다운 형식을 추가하여 해결할 수 있습니다.

// .markdownlint.jsonc
{
    "comment": "Disables rules that may conflict with Prettier",

    "blanks-around-fences": false,
    "blanks-around-headings": false,
    "blanks-around-lists": false,
    "code-fence-style": false,
    "emphasis-style": false,
    "heading-start-left": false,
    "hr-style": false,
    "line-length": false,
    "list-indent": false,
    "list-marker-space": false,
    "no-blanks-blockquote": false,
    "no-hard-tabs": false,
    "no-missing-space-atx": false,
    "no-missing-space-closed-atx": false,
    "no-multiple-blanks": false,
    "no-multiple-space-atx": false,
    "no-multiple-space-blockquote": false,
    "no-multiple-space-closed-atx": false,
    "no-trailing-spaces": false,
    "ol-prefix": false,
    "strong-style": false,
    "ul-indent": false,
}

# markdown
**/*.md