markdownlint 문서 테스트

markdownlint는 Markdown 문법이 특정 규칙을 준수하는지 확인하며, docs-lint 테스트에 사용됩니다.

우리의 문서 스타일 가이드와 마크다운 가이드는 GitLab 문서에 대해 Markdown 문법을 선택할 때 어떤 선택을 해야 하는지 자세히 설명합니다. 이 도구는 이러한 가이드라인에서 벗어난 점을 찾아내는 데 도움을 줍니다.

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

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

markdownlint를 사용할 수 있습니다:

markdownlint 설치

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

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

yarn global add markdownlint-cli

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

yarn global add markdownlint-cli2

image:docs-lint-markdown을 빌드할 때 사용된 markdownlint-cli 또는 markdownlint-cli2 버전을 설치해야 합니다 (확인: variables: 섹션).

편집기에서 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를 로컬에서 실행하기

리포지토리의 어디에서나 markdownlint-cli2를 실행할 수 있습니다. 리포지토리의 루트에서, 구성 파일의 위치를 지정할 필요가 없습니다. 리포지토리의 다른 곳에서 실행할 경우, 구성 파일의 위치를 지정해야 합니다. 이러한 명령어에서, doc/**/*.md를 리포지토리의 Markdown 파일 경로로 바꾸세요:

# 루트 디렉토리에서, 구성 파일을 지정할 필요가 없습니다
$ markdownlint-cli2 'doc/**/*.md'

# 리포지토리의 다른 곳에서, 구성 파일을 지정하세요
$ 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 필요)

추가적으로, 명령어, 매개변수, 값, 파일명 등은 백틱으로 포함되어야 합니다. 예를 들어:

  • “Change the needs keyword in your .gitlab-ci.yml…”
    • needs는 매개변수이고, .gitlab-ci.yml은 파일이므로 두 가지 모두 백틱이 필요합니다. 또한, 백틱 없이 .gitlab-ci.yml은 G나 L이 대문자가 아니기 때문에 markdownlint에서 실패합니다.
  • “Run git clone to clone a Git repository…”
    • git clone은 명령어이므로 소문자로 작성해야 하며, Git은 제품이므로 대문자 G를 포함해야 합니다.