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 분기에 병합되는 것을 방지하지는 않습니다. 콘텐츠에 더 이상 경고 위반이 없으면 대부분의 규칙이 결국 오류로 승격됩니다.
| 규칙 ID | 규칙 이름 | 설명 | 심각도 | 태그 |
|---|---|---|---|---|
| MD001 | heading-increment | 제목 수준은 한 번에 한 수준씩만 증가해야 합니다. | error | 제목 |
| MD004 | ul 스타일 | 순서가 지정되지 않은 목록 스타일 | error | 글머리 기호, ul |
| MD009 | 후행 공백 없음 | 후행 공백 | error | whitespace |
| MD011 | 역방향 링크 없음 | 역방향 링크 구문 | error | 링크 |
| MD012 | 다중 공백 없음 | 여러 개의 연속 공백 줄 | error | 공백, blank_lines |
| MD014 | 결과 표시 명령 | 출력을 표시하지 않고 명령 앞에 사용되는 달러 기호 | error | 코드 |
| MD018 | 누락 공간 atx 없음 | atx 스타일 제목에 해시 후 공백 없음 | error | 제목, atx, 공백 |
| MD019 | 여러 공백 atx 없음 | atx 스타일 머리글에서 해시 후 여러 공백 | error | 제목, atx, 공백 |
| MD022 | blanks-around-headings | 제목은 빈 줄로 둘러싸야 함 | error | 제목, blank_lines |
| MD023 | heading-start-left | 제목은 줄의 시작 부분에서 시작해야 합니다. | error | 제목, 공백 |
| MD027 | 여러 공백 인용구 없음 | 인용구 기호 뒤에 여러 공백 | error | 인용구, 공백, 들여쓰기 |
| MD029 | ol 접두사 | 순서가 지정된 목록 항목 접두사 | error | ol |
| MD030 | 목록 표식 공백 | 목록 표식 뒤에 공백 | error | ol, ul, 공백 |
| MD031 | 공백 주위에 펜싱 | 펜스 코드 블록은 빈 줄로 묶어야 합니다. | error | 코드, blank_lines |
| MD037 | 공백 강조 없음 | 강조 표식 안의 공백 | error | 공백, 강조 |
| MD039 | 링크 내의 공백 없음 | 링크 텍스트 내의 공백 | error | 공백, 링크 |
| MD040 | 펜스 코드 언어 | 펜스 코드 블록에는 언어가 지정되어 있어야 합니다. | error | 코드 언어 |
| MD042 | 빈 링크 없음 | 빈 링크 없음 | error | 링크 |
| MD047 | 단일 후행 줄 | 파일은 단일 줄 문자로 끝나야 합니다. | error | blank_lines |
| MD049 | 강조 스타일 | 강조 스타일 | error | emphasis |
| MD050 | 강력한 스타일 | 강력한 스타일 | error | emphasis |
| 검색 대체 | todocs 개체 틀 | TODOCS 개체 틀의 발생을 포착합니다. | error | |
| 검색 대체 | docs 도메인 | docs.github.com 도메인의 발생을 포착합니다. | error | |
| 검색 대체 | help 도메인인 | help.github.com 도메인의 발생을 포착합니다. | error | |
| 검색 대체 | preview 도메인 | preview.ghdocs.com 도메인의 발생을 포착합니다. | error | |
| 검색 대체 | developer 도메인 | developer.github.com 도메인의 발생을 포착합니다. | error | |
| 검색 대체 | 사용되지 않는 Liquid 구문: site.data | 사용되지 않는 Liquid 데이터 구문의 발생을 포착합니다. | error | |
| 검색 대체 | 사용되지 않는 liquid 구문: octicon- | 사용되는 octicon liquid 구문은 더 이상 사용되지 않습니다. octicon "<octicon-name>" aria-label="<Octicon aria label>" 대신 이 형식 사용 | error | |
| GH001 | 기본 대체 텍스트 없음 | 모든 이미지에는 의미 있는 대체 텍스트가 있어야 합니다. | error | 접근성, 이미지 |
| GH002 | 제네릭 링크 텍스트 없음 | Learn more 혹은 Click here와(과) 같은 제네릭 링크 텍스트 사용 피하기 | error | 접근성, 링크 |
| GHD030 | 코드 펜스 줄 길이 | 코드 펜스 줄은 최대 길이를 초과해서는 안 됩니다. | 경고 | 코드, 접근성 |
| GHD032 | 대체 텍스트 끝 문장 부호 이미지 | 이미지의 대체 텍스트는 문장 부호로 끝나야 합니다. | error | 접근성, 이미지 |
| GHD004 | 이미지 파일 꼬치형 | 이미지 파일 이름은 꼬치형을 사용해야 합니다. | error | images |
| GHD033 | 잘못된 대체 텍스트 길이 | 이미지 대체 텍스트는 40~150자 사이여야 합니다. | 경고 | 접근성, 이미지 |
| GHD002 | 내부 링크 언어 없음 | 내부 링크에는 하드 코딩된 언어 코드가 없어야 합니다. | error | 링크, URL |
| GHD003 | 내부 링크 슬래시 | 내부 링크는 /로 시작해야 합니다. | error | 링크, URL |
| GHD031 | 이미지 대체 텍스트 제외 단어 | 이미지의 대체 텍스트는 "image" 또는 "graphic"과 같은 단어로 시작해서는 안 됩니다. | error | 접근성, 이미지 |
| GHD034 | 목록 첫 번째 단어 대문자 | 목록 항목의 첫 번째 단어를 대문자로 표시해야 합니다. | 경고 | ul, ol |
| GHD001 | 링크 문장 부호 | 내부 링크 제목에 문장 부호가 포함되어서는 안 됩니다. | error | 링크, URL |
| GHD008 | 초기 액세스 참조 | 초기 액세스가 아닌 파일은 초기 액세스 또는 초기 액세스 파일을 참조해서는 안 됩니다. | error | 기능, 초기 액세스 |
| GHD021 | yaml 예약된 작업 | 예약된 워크플로를 포함하는 YAML 코드 조각은 시간에 실행되지 않아야 하며 고유해야 합니다. | error | 기능, 동작 |
| GHD006 | 내부 링크 이전 버전 | 내부 링크에는 이전 버전 관리 구문을 사용하는 하드 코딩된 버전이 없어야 합니다. | error | 링크, URL, 버전 관리 |
| GHD005 | 하드 코딩된 데이터 변수 | "개인용 액세스 토큰"이 포함된 문자열은 제품 변수를 대신 사용해야 합니다. | error | 단일 원본 |
| GHD013 | github 소유 작업 참조 | GitHub 소유 작업 참조를 하드 코딩하면 안 됩니다. | error | 기능, 동작 |
| GHD016 | 조건부 인수로 묶인 liquid | Liquid 조건부 태그는 조건부 인수를 인용해서는 안 됩니다. | error | liquid, 형식 |
| GHD014 | 정의된 liquid 데이터 참조 | liquid 데이터 또는 들여쓰기된 데이터 참조는 값이 없거나 데이터 디렉터리에 없는 콘텐츠에서 발견되었습니다. | error | liquid |
| GHD015 | liquid 데이터 태그 형식 | Liquid 데이터 또는 들여쓰기된 데이터 참조 태그는 올바른 형식이어야 하며 인수의 개수와 간격이 정확해야 합니다. | error | liquid, 형식 |
| GHD010 | 프런트 매터 숨김 docs | 프런트 매터 속성 hidden이(가) 있는 문서는 특정 제품에만 배치할 수 있습니다. | error | 프런트 매터, 기능, 초기 액세스 |
| GHD009 | 프런트 매터 초기 액세스 참조 | 초기 액세스가 아닌 파일에는 초기 액세스를 참조하는 프런트 매터가 없어야 합니다. | error | 프런트 매터, 기능, 초기 액세스 |
| GHD011 | 프런트 매터 비디오 대화록 | 비디오 대화록을 올바르게 구성해야 합니다. | error | 프런트 매터, 기능, 비디오 대화록 |
| GHD012 | 프런트 매터, 스키마 | 프런트 매터는 스키마를 준수해야 합니다. | error | 프런트 매터, 스키마 |
| GHD007 | 코드 주석 | Markdown에 정의된 코드 주석에는 특정 레이아웃 프런트 매터 속성이 포함되어야 합니다. | error | 코드, 기능, 주석, 프런트 매터 |
| GHD017 | 프런트 매터, liquid 구문 | 프런트 매터 속성은 유효한 Liquid를 사용해야 합니다. | error | liquid, 프런트 매터 |
| GHD018 | Liquid 구문 | Markdown 콘텐츠는 유효한 Liquid를 사용해야 합니다. | error | liquid |
| GHD019 | liquid if 태그 | 인수가 유효한 버전인 경우, Liquid ifversion 태그는 if 태그 대신 사용해야 합니다. | error | liquid, 버전 관리 |
| GHD020 | liquid ifversion 태그 | Liquid ifversion 태그는 유효한 버전 이름을 인수로 포함해야 합니다. | error | liquid, 버전 관리 |
| GHD022 | liquid-ifversion-versions | Liquid ifversion(및 elsif)이(가) 항상 참이 되는 것은 아닙니다. | 경고 | liquid, 버전 관리 |
| GHD035 | rai-reusable-usage | RAI 문서와 재사용 가능 요소는 data/reusables/rai 디렉터리의 재사용 가능 콘텐츠만 참조할 수 있음 | error | feature, rai |
| GHD036 | image-no-gif | 이미지는 gif가 아니어야 함, 스타일 가이드 참조: contributing/style-guide-and-content-model/style-guide.md#images | error | images |
| GHD038 | expired-content | 만료된 콘텐츠를 수정해야 합니다. | error | 만료됨 |
| GHD039 | expiring-soon | 곧 만료되는 콘텐츠는 사전에 해결해야 합니다. | 경고 | 만료됨 |
| GHD040 | table-liquid-versioning | 테이블은 올바른 액체 버전 관리 형식을 사용해야 합니다 | error | 테이블 |
| GHD041 | third-party-action-pinning | 써드 파티 액션을 사용하는 코드 예제는 항상 전체 길이의 커밋 SHA에 고정해야 합니다. | error | 기능, 동작 |
| GHD042 | liquid-tag-whitespace | Liquid 태그는 하나의 공백으로 시작하고 끝나야 합니다. Liquid 태그 인수는 하나의 공백으로만 구분해야 합니다. | error | liquid, 형식 |
린팅 규칙 구문
일부 린팅 규칙은 문서에 추가할 수 있는 HTML 주석을 기반으로 경고 또는 오류를 반환합니다.
만료되는 콘텐츠 및 만료된 콘텐츠 구문
규칙 GHD038 및 GHD039는 만료일이 수동으로 지정된 콘텐츠를 검사합니다. 지정된 날짜로부터 14일 전에 콘텐츠 Linter는 콘텐츠가 곧 만료된다는 경고를 반환합니다. 지정된 날짜로부터 콘텐츠 Linter는 오류를 반환하고 수정을 위해 콘텐츠에 플래그를 지정합니다.
만료일을 <!-- expires yyyy-mm-dd --> <!-- end expires yyyy-mm-dd --> 형식으로 포함하는 HTML 태그로 래핑하여 콘텐츠에 만료일을 추가할 수 있습니다.
올바른 사용:
This content does not expire.
<!-- expires 2022-01-28 -->
This content expires on January 28, 2022.
<!-- end expires 2022-01-28 -->
This content also does not expire.
HTML table 요소에 만료된 태그를 배치하는 경우 태그가 셀뿐만 아니라 전체 행을 따라 이동해야 합니다. 예시:
<!-- expires 2024-06-28 -->
<tr>
<td>
macOS
</td>
<td>
The <code>macos-11</code> label is 사용되지 않음 and will no longer be available after 28 June 2024.
</td>
</tr>
<!-- end expires 2024-06-28 -->
Linter 규칙 표시 안 하기
드물게 하나 이상의 Linter 규칙을 위반하는 항목을 문서화해야 할 수도 있습니다. 이러한 경우 Markdown 파일에 주석을 추가하여 규칙을 표시하지 않을 수 있습니다. 모든 규칙 또는 특정 규칙을 사용하지 않도록 설정할 수 있습니다. 항상 가능한 한 적은 규칙을 제한하려고 합니다. 전체 파일, Markdown 파일의 섹션, 특정 줄 또는 다음 줄에 대한 규칙을 사용하지 않도록 설정할 수 있습니다.
예를 들어 역방향 링크 구문에 대해 검사 정규식 (^|/)[Cc]+odespace/을(를) 포함하는 문서를 작성하는 경우, 역방향 링크에 대해 검사 규칙 MD011이(가) 트리거됩니다. 다음 주석을 추가하여 특정 줄에서 규칙 MD011을(를) 사용하지 않도록 설정할 수 있습니다.
(^|/)[Cc]+odespace/ <!-- markdownlint-disable-line MD011 -->
무시하려는 줄이 코드 블록에 있는 경우, 다음 주석으로 코드 블록을 둘러싸고 무시해도 됩니다.
<!-- markdownlint-disable MD011 -->
```
(^|/)[Cc]+odespace/
```
<!-- markdownlint-enable MD011 -->
이러한 주석을 사용하여 규칙을 사용하거나 사용하지 않도록 설정할 수 있습니다.
| Comment(설명) | 효과 |
|---|---|
<!-- 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 --> | 다음 줄의 이름으로 하나 이상의 규칙을 사용하지 않도록 설정하기 |