Skip to main content

이 버전의 GitHub Enterprise Server는 다음 날짜에 중단됩니다. 2024-08-29. 중요한 보안 문제에 대해서도 패치 릴리스가 이루어지지 않습니다. 더 뛰어난 성능, 향상된 보안, 새로운 기능을 위해 최신 버전의 GitHub Enterprise Server로 업그레이드합니다. 업그레이드에 대한 도움말은 GitHub Enterprise 지원에 문의하세요.

콘텐츠 Linter 사용

콘텐츠 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를 로컬로 실행합니다. warningerror 심각도 결함을 모두 출력합니다.

npm run lint-content

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

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

npm run lint-content -- --errors

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

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

Shell
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-incrementcode-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규칙 이름설명심각도태그
MD001heading-increment제목 수준은 한 번에 한 수준씩만 증가해야 합니다.error제목
MD004ul 스타일순서가 지정되지 않은 목록 스타일error글머리 기호, ul
MD009후행 공백 없음후행 공백errorwhitespace
MD011역방향 링크 없음역방향 링크 구문error링크
MD012다중 공백 없음여러 개의 연속 공백 줄error공백, blank_lines
MD014결과 표시 명령출력을 표시하지 않고 명령 앞에 사용되는 달러 기호error코드
MD018누락 공간 atx 없음atx 스타일 제목에 해시 후 공백 없음error제목, atx, 공백
MD019여러 공백 atx 없음atx 스타일 머리글에서 해시 후 여러 공백error제목, atx, 공백
MD022blanks-around-headings제목은 빈 줄로 둘러싸야 함error제목, blank_lines
MD023heading-start-left제목은 줄의 시작 부분에서 시작해야 합니다.error제목, 공백
MD027여러 공백 인용구 없음인용구 기호 뒤에 여러 공백error인용구, 공백, 들여쓰기
MD029ol 접두사순서가 지정된 목록 항목 접두사errorol
MD030목록 표식 공백목록 표식 뒤에 공백errorol, ul, 공백
MD031공백 주위에 펜싱펜스 코드 블록은 빈 줄로 묶어야 합니다.error코드, blank_lines
MD037공백 강조 없음강조 표식 안의 공백error공백, 강조
MD039링크 내의 공백 없음링크 텍스트 내의 공백error공백, 링크
MD040펜스 코드 언어펜스 코드 블록에는 언어가 지정되어 있어야 합니다.error코드 언어
MD042빈 링크 없음빈 링크 없음error링크
MD047단일 후행 줄파일은 단일 줄 문자로 끝나야 합니다.errorblank_lines
MD049강조 스타일강조 스타일erroremphasis
MD050강력한 스타일강력한 스타일erroremphasis
검색 대체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이미지 파일 꼬치형이미지 파일 이름은 꼬치형을 사용해야 합니다.errorimages
GHD033잘못된 대체 텍스트 길이이미지 대체 텍스트는 40~150자 사이여야 합니다.경고접근성, 이미지
GHD002내부 링크 언어 없음내부 링크에는 하드 코딩된 언어 코드가 없어야 합니다.error링크, URL
GHD003내부 링크 슬래시내부 링크는 /로 시작해야 합니다.error링크, URL
GHD031이미지 대체 텍스트 제외 단어이미지의 대체 텍스트는 "image" 또는 "graphic"과 같은 단어로 시작해서는 안 됩니다.error접근성, 이미지
GHD034목록 첫 번째 단어 대문자목록 항목의 첫 번째 단어를 대문자로 표시해야 합니다.경고ul, ol
GHD001링크 문장 부호내부 링크 제목에 문장 부호가 포함되어서는 안 됩니다.error링크, URL
GHD008초기 액세스 참조초기 액세스가 아닌 파일은 초기 액세스 또는 초기 액세스 파일을 참조해서는 안 됩니다.error기능, 초기 액세스
GHD021yaml 예약된 작업예약된 워크플로를 포함하는 YAML 코드 조각은 시간에 실행되지 않아야 하며 고유해야 합니다.error기능, 동작
GHD006내부 링크 이전 버전내부 링크에는 이전 버전 관리 구문을 사용하는 하드 코딩된 버전이 없어야 합니다.error링크, URL, 버전 관리
GHD005하드 코딩된 데이터 변수"개인용 액세스 토큰"이 포함된 문자열은 제품 변수를 대신 사용해야 합니다.error단일 원본
GHD013github 소유 작업 참조GitHub 소유 작업 참조를 하드 코딩하면 안 됩니다.error기능, 동작
GHD016조건부 인수로 묶인 liquidLiquid 조건부 태그는 조건부 인수를 인용해서는 안 됩니다.errorliquid, 형식
GHD014정의된 liquid 데이터 참조liquid 데이터 또는 들여쓰기된 데이터 참조는 값이 없거나 데이터 디렉터리에 없는 콘텐츠에서 발견되었습니다.errorliquid
GHD015liquid 데이터 태그 형식Liquid 데이터 또는 들여쓰기된 데이터 참조 태그는 올바른 형식이어야 하며 인수의 개수와 간격이 정확해야 합니다.errorliquid, 형식
GHD010프런트 매터 숨김 docs프런트 매터 속성 hidden이(가) 있는 문서는 특정 제품에만 배치할 수 있습니다.error프런트 매터, 기능, 초기 액세스
GHD009프런트 매터 초기 액세스 참조초기 액세스가 아닌 파일에는 초기 액세스를 참조하는 프런트 매터가 없어야 합니다.error프런트 매터, 기능, 초기 액세스
GHD011프런트 매터 비디오 대화록비디오 대화록을 올바르게 구성해야 합니다.error프런트 매터, 기능, 비디오 대화록
GHD012프런트 매터, 스키마프런트 매터는 스키마를 준수해야 합니다.error프런트 매터, 스키마
GHD007코드 주석Markdown에 정의된 코드 주석에는 특정 레이아웃 프런트 매터 속성이 포함되어야 합니다.error코드, 기능, 주석, 프런트 매터
GHD017프런트 매터, liquid 구문프런트 매터 속성은 유효한 Liquid를 사용해야 합니다.errorliquid, 프런트 매터
GHD018Liquid 구문Markdown 콘텐츠는 유효한 Liquid를 사용해야 합니다.errorliquid
GHD019liquid if 태그인수가 유효한 버전인 경우, Liquid ifversion 태그는 if 태그 대신 사용해야 합니다.errorliquid, 버전 관리
GHD020liquid ifversion 태그Liquid ifversion 태그는 유효한 버전 이름을 인수로 포함해야 합니다.errorliquid, 버전 관리
GHD022liquid-ifversion-versionsLiquid ifversion(및 elsif)이(가) 항상 참이 되는 것은 아닙니다.경고liquid, 버전 관리
GHD035rai-reusable-usageRAI 문서와 재사용 가능 요소는 data/reusables/rai 디렉터리의 재사용 가능 콘텐츠만 참조할 수 있음errorfeature, rai
GHD036image-no-gif이미지는 gif가 아니어야 함, 스타일 가이드 참조: contributing/style-guide-and-content-model/style-guide.md#imageserrorimages
GHD038expired-content만료된 콘텐츠를 수정해야 합니다.error만료됨
GHD039expiring-soon곧 만료되는 콘텐츠는 사전에 해결해야 합니다.경고만료됨

린팅 규칙 구문

일부 린팅 규칙은 문서에 추가할 수 있는 HTML 주석을 기반으로 경고 또는 오류를 반환합니다.

만료되는 콘텐츠 및 만료된 콘텐츠 구문

규칙 GHD038GHD039는 만료일이 수동으로 지정된 콘텐츠를 검사합니다. 지정된 날짜로부터 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 has been deprecated 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 -->다음 줄의 이름으로 하나 이상의 규칙을 사용하지 않도록 설정하기