• markdownlint 설치
• 코드 편집기에서 markdownlint 구성
• markdownlint 테스트 비활성화
• 문제해결
  • Markdown 규칙 MD044/proper-names (대문자)

markdownlint 문서 테스트

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

저희의 문서 양식 가이드 및 Markdown 가이드는 GitLab 문서의 Markdown 구문을 선택할 때 필요한 선택 사항에 대해 상세히 다루고 있습니다. 이 도구는 해당 가이드라인에서의 벗어남을 찾아냅니다.

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

• gitlab
• gitlab-runner
• omnibus-gitlab
• charts
• gitlab-development-kit
• gitlab-operator

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

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

• 명령줄에서 다음 중 하나로:
  • markdownlint-cli.
  • markdownlint-cli2.
• 코드 편집기에서.
• 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이어야 합니다.