콘텐츠 Linter 사용

GitHub Docs 콘텐츠 Linter 정보

콘텐츠 Linter는 Markdown 콘텐츠에 스타일 가이드 규칙을 적용합니다.

Linter는 가능한 경우 markdownlint을(를) 프레임워크로 사용하여 검사를 수행하고 결함을 보고하며 콘텐츠를 자동으로 수정합니다. 이 프레임워크는 특정 규칙을 유연하게 실행하고, 설명적인 오류 메시지를 제공하고, 오류를 수정합니다. GitHub Docs 콘텐츠 linter는 여러 기존 markdownlint 규칙 및 추가 사용자 지정 규칙을 사용하여 Microsoft 및 content, data 디렉터리에서 Markdown 콘텐츠를 검사합니다. 사용자 지정 규칙은 markdownlint 프레임워크에서 아직 사용할 수 없거나 GitHub Docs 콘텐츠와 관련된 검사를 구현합니다. 규칙은 Markdown과 Liquid 모두에 대한 구문을 검사합니다.

GitHub Docs 콘텐츠 Linter 실행

GitHub Docs 콘텐츠 linter는 사전 커밋 시 자동으로 실행되지만 수동으로 실행할 수도 있습니다.

사전 커밋에서 Linter 자동 실행

로컬로 콘텐츠를 작성하고 명령줄을 사용하여 파일을 커밋하는 경우, 해당 스테이징된 파일은 콘텐츠 Linter에 의해 자동으로 linted됩니다. 경고와 오류가 모두 보고되지만 오류만 커밋이 완료되지 않습니다.

오류가 보고되면 커밋이 완료되지 않습니다. 보고된 오류를 수정하고, 변경된 파일을 다시 추가하고, 변경 내용을 다시 커밋해야 합니다. 보고된 오류는 GitHub Docs 스타일 가이드를 위반하는 콘텐츠에 오류가 발생하지 않도록 수정해야 합니다. 경고가 보고되면 필요에 따라 경고를 수정할지의 여부를 선택할 수 있습니다.

로컬로 콘텐츠를 작성할 때 명령줄을 사용하여 자동으로 수정할 수 있는 몇 가지 규칙이 있습니다. 수정할 수 있는 오류를 자동으로 수정하려면 "수정할 수 있는 오류 자동 수정"을 참조하세요.

GitHub UI에서 파일을 편집하는 경우 오류를 자동으로 수정하거나 커밋에서 linter를 실행할 수 없지만 콘텐츠가 심각도 error의 규칙을 위반하는 경우 CI 오류가 발생합니다.

Linter 수동 실행하기

스테이징 및 변경된 파일에서 Linter 실행하기

다음 명령을 사용하여 스테이징 및 변경된 파일에서 Linter를 로컬로 실행합니다. warning 및 error 심각도 결함을 모두 출력합니다.

npm run lint-content

스테이징 및 변경된 파일과 보고된 오류에 Linter 실행하기

다음 명령을 사용하여 스테이징 및 변경된 파일, error 심각도 결함 보고에서 Linter를 로컬로 실행합니다.

npm run lint-content -- --errors

특정 파일 또는 디렉터리에서 Linter 실행하기

다음 명령을 사용하여 특정 파일 또는 디렉터리에서 Linter를 로컬로 실행합니다. 여러 경로를 쉼표로 구분합니다. 동일한 명령에 파일과 디렉터리를 모두 포함할 수 있습니다.

npm run lint-content -- \
  --paths content/FILENAME.md content/DIRECTORY

npm run lint-content -- \
  --paths content/FILENAME.md content/DIRECTORY

수정할 수 있는 오류 자동 수정하기

설명 오류에 fixable: true이(가) 있는 경우, 다음 명령을 사용하여 자동으로 수정할 수 있습니다.

이 명령을 실행하여 스테이징된 파일과 변경된 파일만 수정합니다.

npm run lint-content -- --fix

이 명령을 실행하여 특정 파일 또는 디렉터리를 수정합니다.

npm run lint-content -- \
  --fix --paths content/FILENAME.md content/DIRECTORY

특정 Linter 규칙 집합 실행하기

다음 명령을 사용하여 하나 이상의 특정 Linter 규칙을 실행합니다. 이러한 예제는 heading-increment 및 code-fence-line-length 규칙을 실행합니다. heading-increment code-fence-line-length을(를) 실행하려는 하나 이상의 Linter 별칭으로 대체합니다. 이 옵션에 전달할 수 있는 Linter 규칙 목록을 보려면 npm run lint-content -- --help을(를) 실행합니다. Linter 규칙에 짧은 이름(예: MD001)이나 긴 이름(예: heading-increment)을 사용할 수 있습니다.

모든 스테이징 및 변경된 파일에서 특정 Linter 규칙 실행하기

npm run lint-content -- \
  --rules heading-increment code-fence-line-length

특정 파일 또는 디렉터리에서 Linter 규칙 실행하기

npm run lint-content -- \
  --rules heading-increment code-fence-line-length \
  --path content/FILENAME.md content/DIRECTORY

커밋 후크 무시하기

Linter가 도입하지 않은 오류를 포착하는 경우, 변경 내용을 커밋할 때 --no-verify 옵션을 사용하여 git 커밋 후크를 무시할 수 있습니다.

git commit -m 'MESSAGE' --no-verify

콘텐츠 Linter 스크립트에 대한 도움말 메뉴 표시하기

npm run lint-content -- --help

린팅 규칙

각 규칙은 규칙의 심각도가 정의된 파일 src/content-linter/style에서 구성됩니다.

main 분기의 변경 내용을 병합하기 전에 오류를 해결해야 합니다. 경고는 해결해야 하지만 변경 내용이 main 분기에 병합되는 것을 방지하지는 않습니다. 콘텐츠에 더 이상 경고 위반이 없으면 대부분의 규칙이 결국 오류로 승격됩니다.

Linter 규칙 표시 안 하기

드물게 하나 이상의 Linter 규칙을 위반하는 항목을 문서화해야 할 수도 있습니다. 이러한 경우 Markdown 파일에 주석을 추가하여 규칙을 표시하지 않을 수 있습니다. 모든 규칙 또는 특정 규칙을 사용하지 않도록 설정할 수 있습니다. 항상 가능한 한 적은 규칙을 제한하려고 합니다. 전체 파일, Markdown 파일의 섹션, 특정 줄 또는 다음 줄에 대한 규칙을 사용하지 않도록 설정할 수 있습니다.

예를 들어 역방향 링크 구문에 대해 검사 정규식 (^|/)[Cc]+odespace/을(를) 포함하는 문서를 작성하는 경우, 역방향 링크에 대해 검사 규칙 MD011이(가) 트리거됩니다. 다음 주석을 추가하여 특정 줄에서 규칙 MD011을(를) 사용하지 않도록 설정할 수 있습니다.

(^|/)[Cc]+odespace/ <!-- markdownlint-disable-line MD011 -->

무시하려는 줄이 코드 블록에 있는 경우, 다음 주석으로 코드 블록을 둘러싸고 무시해도 됩니다.

<!-- markdownlint-disable MD011 -->
```
(^|/)[Cc]+odespace/
```
<!-- markdownlint-enable MD011 -->

이러한 주석을 사용하여 규칙을 사용하거나 사용하지 않도록 설정할 수 있습니다.

<!-- markdownlint-disable -->

<!-- markdownlint-enable -->

<!-- markdownlint-disable-line -->

<!-- markdownlint-disable-next-line -->

<!-- markdownlint-disable RULE-ONE RULE-TWO -->

<!-- markdownlint-enable RULE-ONE RULE-TWO -->

<!-- markdownlint-disable-line RULE-NAME -->

<!-- markdownlint-disable-next-line RULE-NAME -->