InfoGrab DocsInfoGrab Docs

markdownlint 문서 테스트

요약

markdownlint는 Markdown 구문이 특정 규칙을 따르는지 검사하며, docs-lint 테스트에서 사용됩니다. 문서 스타일 가이드와 Markdown 가이드에서는 GitLab 문서에 사용할 Markdown 구문을 선택할 때 어떤 선택을 해야 하는지 상세히 설명합니다.

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

문서 스타일 가이드와 Markdown 가이드에서는 GitLab 문서에 사용할 Markdown 구문을 선택할 때 어떤 선택을 해야 하는지 상세히 설명합니다. 이 도구는 해당 지침으로부터의 이탈을 잡아내는 데 도움이 됩니다.

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

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

markdownlint는 다음과 같은 방법으로 사용할 수 있습니다:

  • 커맨드라인에서 다음 중 하나를 사용:

markdownlint-cli.

markdownlint 설치#

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

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

yarn global add markdownlint-cli

markdownlint-cli2를 설치하려면:

  • mise를 사용하는 경우, 다음을 실행하세요:
mise use -g markdownlint-cli2
  • yarn을 사용하는 경우, 다음을 실행하세요:
yarn global add markdownlint-cli2

GitLab Docs 프로젝트에서 사용하는 버전과 일치하는 markdownlint-cli 또는 markdownlint-cli2 버전을 설치해야 합니다. 올바른 버전은 variables: 섹션에서 확인할 수 있습니다.

에디터에서 markdownlint 구성#

에디터에서 markdownlint를 사용하면 커맨드라인에서 명령어를 실행하는 것보다 더 편리합니다.

에디터에서 markdownlint를 구성하려면 다음 중 적절한 것을 설치하세요:

"markdownlint": {
  "executable": [ "markdownlint-cli2" ]
}

  • Vim ALE 플러그인.

  • Emacs Flycheck 확장. Flycheck는 기본적으로 markdownlint-cli를 지원하지만, 프로젝트 디렉터리의 루트에 있는 .markdownlint.yml을 가리키도록 .dir-locals.el 파일을 추가해야 합니다:

;; Place this code in a file called `.dir-locals.el` at the root of the gitlab project.
((markdown-mode . ((flycheck-markdown-markdownlint-cli-config . ".markdownlint.yml"))))

로컬에서 markdownlint-cli2 실행#

리포지터리의 어디서든 markdownlint-cli2를 실행할 수 있습니다. 리포지터리의 루트에서 실행하면 설정 파일의 위치를 지정할 필요가 없습니다. 리포지터리의 다른 위치에서 실행하는 경우에는 설정 파일의 위치를 지정해야 합니다. 이 명령어에서 doc/**/*.md를 리포지터리의 Markdown 파일 경로로 교체하세요:

# From the root directory, you don't need to specify the configuration file
markdownlint-cli2 'doc/**/*.md'

# From elsewhere in the repository, specify the configuration file
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가 있어야 합니다.

markdownlint 문서 테스트

GitLab v19.1
원문 보기
요약

markdownlint는 Markdown 구문이 특정 규칙을 따르는지 검사하며, docs-lint 테스트에서 사용됩니다. 문서 스타일 가이드와 Markdown 가이드에서는 GitLab 문서에 사용할 Markdown 구문을 선택할 때 어떤 선택을 해야 하는지 상세히 설명합니다.

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

문서 스타일 가이드와 Markdown 가이드에서는 GitLab 문서에 사용할 Markdown 구문을 선택할 때 어떤 선택을 해야 하는지 상세히 설명합니다. 이 도구는 해당 지침으로부터의 이탈을 잡아내는 데 도움이 됩니다.

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

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

markdownlint는 다음과 같은 방법으로 사용할 수 있습니다:

  • 커맨드라인에서 다음 중 하나를 사용:

markdownlint-cli.

markdownlint 설치#

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

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

yarn global add markdownlint-cli

markdownlint-cli2를 설치하려면:

  • mise를 사용하는 경우, 다음을 실행하세요:
mise use -g markdownlint-cli2
  • yarn을 사용하는 경우, 다음을 실행하세요:
yarn global add markdownlint-cli2

GitLab Docs 프로젝트에서 사용하는 버전과 일치하는 markdownlint-cli 또는 markdownlint-cli2 버전을 설치해야 합니다. 올바른 버전은 variables: 섹션에서 확인할 수 있습니다.

에디터에서 markdownlint 구성#

에디터에서 markdownlint를 사용하면 커맨드라인에서 명령어를 실행하는 것보다 더 편리합니다.

에디터에서 markdownlint를 구성하려면 다음 중 적절한 것을 설치하세요:

"markdownlint": {
  "executable": [ "markdownlint-cli2" ]
}

  • Vim ALE 플러그인.

  • Emacs Flycheck 확장. Flycheck는 기본적으로 markdownlint-cli를 지원하지만, 프로젝트 디렉터리의 루트에 있는 .markdownlint.yml을 가리키도록 .dir-locals.el 파일을 추가해야 합니다:

;; Place this code in a file called `.dir-locals.el` at the root of the gitlab project.
((markdown-mode . ((flycheck-markdown-markdownlint-cli-config . ".markdownlint.yml"))))

로컬에서 markdownlint-cli2 실행#

리포지터리의 어디서든 markdownlint-cli2를 실행할 수 있습니다. 리포지터리의 루트에서 실행하면 설정 파일의 위치를 지정할 필요가 없습니다. 리포지터리의 다른 위치에서 실행하는 경우에는 설정 파일의 위치를 지정해야 합니다. 이 명령어에서 doc/**/*.md를 리포지터리의 Markdown 파일 경로로 교체하세요:

# From the root directory, you don't need to specify the configuration file
markdownlint-cli2 'doc/**/*.md'

# From elsewhere in the repository, specify the configuration file
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가 있어야 합니다.