markdownlint 문서 테스트
markdownlint는 Markdown 구문이 특정 규칙을 따르는지 확인하고 docs-lint
테스트에서 사용됩니다.
저희의 문서 양식 가이드 및 Markdown 가이드는 GitLab 문서의 Markdown 구문을 선택할 때 필요한 선택 사항에 대해 상세히 다루고 있습니다. 이 도구는 해당 가이드라인에서의 벗어남을 찾아냅니다.
markdownlint 구성은 다음 프로젝트에서 찾을 수 있습니다:
이 구성은 빌드 파이프라인에서도 사용됩니다.
markdownlint를 다음과 같이 사용할 수 있습니다:
- 명령줄에서 다음 중 하나로:
- 코드 편집기에서.
-
pre-push
후크에서.
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
은 대문자 G나 L이 없기 때문에 markdownlint에서 실패합니다.
-
- “Git 리포지터리를 클론하려면
git clone
을 실행하십시오…”-
git clone
은 명령이므로 소문자이어야 하고, Git은 제품이므로 대문자 G이어야 합니다.
-