markdownlint 문서 테스트

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

우리의 문서 스타일 가이드와 Markdown 가이드는 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의 버전을 설치해야 합니다. 사용됩니다 (해당 variables: 섹션 참조) 빌드 시 image:docs-lint-markdown를 만들 때.

코드 에디터에서 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 테스트 비활성화

모든 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은 파일이므로 둘 다 백틱이 필요합니다. 게다가 백틱 없이 표시된 .gitlab-ci.yml은 markdownlint에서 실패하며 그 이유는 G나 L이 대문자로 표시되지 않았기 때문입니다.
  • “Git 리포지터리를 복제하려면 git clone을 실행하세요…”
    • git clone은 명령어이므로 소문자이어야 하지만 Git은 제품이므로 대문자 G가 필요합니다.