• 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의 버전을 설치해야 합니다. 사용된 버전 (변수 확인)하고 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 clone 명령을 실행하여 Git 리포지토리를 복제하세요…”
  • git clone은 명령어이므로 소문자이어야 하고, Git은 제품이므로 대문자 G를 가져야 합니다.