markdownlint 문서 테스트

markdownlint는 Markdown 구문이 특정 규칙을 따르는지를 확인하고 docs-lint 테스트에서 사용됩니다.

저희의 Documentation Style Guide와 Markdown Guide는 GitLab 문서에 Markdown 구문을 선택할 때 필요한 선택 사항에 대해 자세히 다룹니다. 이 도구는 해당 지침에서의 이탈을 찾아내는 데 도움이 됩니다.

markdownlint 구성은 다음 프로젝트에서 찾을 수 있습니다:

이 구성은 빌드 파이프라인에서도 사용됩니다.

markdownlint를 다음과 같이 사용할 수 있습니다:

markdownlint 설치

markdownlint-cli 또는 markdownlint-cli2 중 하나를 설치하여 markdownlint를 실행할 수 있습니다.

markdownlint-cli를 설치하려면 다음을 실행하세요: 

yarn global add markdownlint-cli

markdownlint-cli2를 설치하려면 다음을 실행하세요: 

yarn global add markdownlint-cli2

markdownlint-cli 또는 markdownlint-cli2의 사용된 버전(see variables: section)을 빌드할 때 사용해야 합니다.

에디터에서 markdownlint 구성

에디터에서 markdownlint를 구성하는 것이 명령줄에서 명령을 실행하는 것보다 편리합니다.

에디터에서 markdownlint를 구성하려면 다음 중 적합한 것을 설치하세요:

  • Visual Studio Code DavidAnson.vscode-markdownlint 익스텐션.

  • Sublime Text SublimeLinter-contrib-markdownlint 패키지. 이 패키지는 기본적으로 markdownlint-cli를 사용하지만, 다음의 SublimeLinter 구성으로 markdownlint-cli2를 사용하도록 구성할 수 있습니다: 

    "markdownlint": {
  "executable": [ "markdownlint-cli2" ]
}
  • Vim ALE 플러그인.

  • Emacs Flycheck 익스텐션. Flycheck는 기본적으로 markdownlint-cli를 지원하지만, 프로젝트 디렉터리의 .markdownlint.yml을 가리키도록 .dir-locals.el 파일을 추가해주어야 합니다: 

    ;; 이 코드를 gitlab 프로젝트의 루트에 `.dir-locals.el`이라는 이름의 파일에 넣어주세요.
((markdown-mode . ((flycheck-markdown-markdownlint-cli-config . ".markdownlint.yml"))))

로컬에서 markdownlint-cli2 실행

repository의 어디서든 markdownlint-cli2를 실행할 수 있습니다. repository의 루트에서 실행할 경우 구성 파일의 위치를 명시할 필요가 없습니다. repository의 다른 위치에서 실행할 경우 이 명령어들에서 doc/**/*.md를 귀하의 repository 내의 Markdown 파일 경로로 대체해주세요: 

# 루트 디렉토리에서 실행할 경우 구성 파일을 명시할 필요가 없습니다
$ markdownlint-cli2 'doc/**/*.md'

# repository의 다른 위치에서 실행할 경우 구성 파일을 명시해야 합니다
$ markdownlint-cli2 --config .markdownlint-cli2.yaml 'doc/**/*.md'

명령줄 옵션의 전체 목록은 markdownlint-cli2 문서의 Command Line를 참조하세요.

markdownlint 테스트 비활성화

모든 markdownlint 규칙을 비활성화하려면 텍스트 앞에 <!-- markdownlint-disable --> 태그를 추가하고, 텍스트 뒤에 <!-- markdownlint-enable --> 태그를 추가하세요.

특정 규칙만 비활성화하려면, 예를 들어 규칙 번호를 태그에 추가하세요. 예시: <!-- markdownlint-disable MD044 -->와 <!-- markdownlint-enable MD044 -->.

가능한 경우 문제가 되는 라인만 제외하세요.

문제 해결

Markdown 규칙 MD044/proper-names (대문자화)

혼란을 줄 수 있는 규칙 중 하나는 MD044/proper-names입니다. 실패 또는 수정하는 방법이 바로 이해되지 않을 수 있습니다. 이 규칙은 각 프로젝트의 .markdownlint.yml 파일에 나열된 알려진 단어 목록을 확인하여 대문자화 및 백틱의 올바른 사용을 검사합니다. 백틱으로 감싸인 단어는 markdownlint에서 무시됩니다.

일반적으로, 제품 이름은 제품, 프로토콜 등의 공식 이름의 정확한 대문자화를 따라야 합니다.

잘못된 대문자화로 인해 일부 예시는 실패합니다:

  • MinIO (IO는 대문자여야 함)
  • NGINX (모든 글자가 대문자여야 함)
  • runit (r은 소문자여야 함)

또한, 명령어, 매개변수, 값, 파일명 등은 모두 백틱에 포함되어야 합니다. 예시:

  • ”.gitlab-ci.yml에서 needs 키워드를 변경하세요…”
    • needs는 매개변수이며, .gitlab-ci.yml은 파일이므로 둘 다 백틱으로 감싸야 합니다. 또한, 백틱 없이는 markdownlint에 실패하므로 .gitlab-ci.yml은 대문자 G나 L을 가지고 있지 않습니다.
  • “Git 리포지토리를 복제하려면 git clone을 실행하세요…”
    • git clone은 명령어이므로 소문자이어야 하며, Git은 제품이므로 대문자 G를 가져야 합니다.