GitLab 문서는 코드와 함께 프로젝트에 저장되며, 코드와 동일하게 취급됩니다. 문서의 표준과 품질을 유지하기 위해 코드에서 사용하는 것과 유사한 프로세스를 사용합니다.

Markdown(.md) 파일의 변경을 포함한 머지 리퀘스트는 다음 CI/CD job을 실행합니다:

• docs-lint markdown: 다음을 포함한 여러 유형의 테스트를 실행합니다:

Vale: 문서 콘텐츠를 검사합니다.

• markdownlint: Markdown 구조를 검사합니다.

• lint-docs.sh 스크립트: 기타 테스트

• docs-lint links: 문서 모음 내 상대 링크의 유효성을 검사합니다.

• docs-lint mermaid: mermaidlint를 실행하여 유효하지 않은 Mermaid 차트를 검사합니다.

• rubocop-docs: .rb 파일의 문서 링크를 검사합니다.

• eslint-docs: .js 및 .vue 파일의 문서 링크를 검사합니다.

• docs-lint redirects: 리디렉션 없이 삭제되거나 이름이 변경된 문서 파일을 검사합니다.

• docs code_quality 및 code_quality cache: 코드 품질을 실행하여 Vale 경고 및 오류를 MR 변경 탭(diff 뷰)에 추가합니다.

• docs hugo_build: 테스트 전용 설정을 사용하여 Hugo 웹사이트의 부분 빌드를 실행하고 shortcode 및 파일명을 검증합니다.

일부 파일은 스크립트로 생성됩니다. 소스 코드 파일이나 문서 파일이 올바른 프로세스를 따르지 않고 업데이트되면 CI/CD job이 실패합니다:

• graphql-verify: doc/api/graphql/reference/_index.md가 업데이트 프로세스에 따라 업데이트되지 않으면 실패합니다.

• docs-lint deprecations-and-removals: doc/update/deprecations.md가 업데이트 프로세스에 따라 업데이트되지 않으면 실패합니다.

자동화된 파일의 전체 목록은 자동화된 페이지를 참조하세요.

lint-doc.sh의 테스트#

/scripts/lint-doc.sh의 테스트는 Vale와 markdownlint로 테스트할 수 없는 페이지 콘텐츠 문제를 찾습니다. 다음 lint-doc.sh 테스트 중 하나라도 실패하면 docs-lint markdown job이 실패합니다:

• Curl(curl) 명령어는 짧은 옵션(예: -h) 대신 긴 형식 옵션(--header)을 사용해야 합니다.

• 문서 페이지에는 페이지 소유권을 나타내는 프론트매터가 포함되어야 합니다.

• CHANGELOG.md에 중복된 버전이 없어야 합니다.

• doc/ 디렉터리의 파일은 실행 권한이 없어야 합니다.

• 파일명 및 디렉터리는 다음 조건을 충족해야 합니다:

README.md 대신 _index.md를 사용해야 합니다.

• 소문자여야 합니다.

• 이미지 파일명은 추가된 버전을 명시해야 합니다.

• Mermaid 차트는 오류 없이 렌더링되어야 합니다.

Mermaid 차트 린팅#

히스토리

• GitLab 16.10에서 도입됨.

Mermaid는 코드로 차트와 다이어그램을 작성합니다.

스크립트(scripts/lint/check_mermaid.mjs)는 Markdown 파일 변경을 포함한 모든 머지 리퀘스트에 대해 docs-lint mermaid job에서 실행됩니다. Markdown 파일에서 Mermaid 문법 오류가 반환되면 스크립트는 오류를 반환합니다.

Mermaid 차트 디버깅을 위해 Mermaid 라이브 에디터를 사용하세요.

docs-lint links 및 기타 job의 테스트#

끊어진 링크를 검사하기 위해, Markdown(.md) 파일 변경을 포함한 머지 리퀘스트는 파이프라인에서 다음 job을 실행합니다:

• gitlab 프로젝트의 docs-lint links job. 예: https://gitlab.com/gitlab-org/gitlab/-/jobs/7065686331.

• omnibus-gitlab 프로젝트의 docs-lint links job. 예: https://gitlab.com/gitlab-org/omnibus-gitlab/-/jobs/7065337075.

• gitlab-operator 프로젝트의 docs-lint links job.

• gitlab-runner 프로젝트의 docs:lint markdown job(링크 검사 포함). 예: https://gitlab.com/gitlab-org/gitlab-runner/-/jobs/7056674997.

• charts/gitlab 프로젝트의 check_docs_links job. 예: https://gitlab.com/gitlab-org/charts/gitlab/-/jobs/7066011619.

이 job들은 앵커 링크를 포함한 링크를 검사하고 문제를 보고합니다. 네트워크 연결이 필요한 링크는 건너뜁니다.

번역 문서 테스트#

번역된 모든 콘텐츠의 품질을 보장하기 위해, /doc-locale/ 또는 /docs-locale/ 디렉터리에 있는 여러 언어의 국제화 콘텐츠에 대한 테스트를 구현했습니다. 이 테스트는 영어 버전에 사용되는 테스트와 동일합니다.

일반 번역 린팅#

docs-i18n-lint markdown job은 모든 번역 문서에 대해 일반 린팅 테스트를 실행합니다:

• markdownlint: Markdown 구조 및 형식을 검사합니다.

• Vale: gitlab_docs 필터를 사용하여 일반 문서 스타일 규칙을 실행합니다.

이 job은 /doc-locale/ 또는 /docs-locale/의 파일이 수정될 때 실행되며, 모든 번역 콘텐츠에 대한 기본 품질 검사를 제공합니다.

언어별 번역 린팅#

특정 스타일 요구 사항이 있는 언어에 대해, 언어별 Vale 규칙을 실행하는 전용 CI/CD job을 제공합니다. 각 언어에는 해당 언어의 파일이 수정될 때만 실행되는 고유한 job이 있습니다.

일본어 지원#

docs-i18n-lint japanese-vale job은 일본어 전용 Vale 린팅을 실행합니다:

• 스크립트: scripts/i18n_lint_language_vale.sh

• 설정: doc-locale/ja-jp/.vale.ini

• Vale 필터: locale_rules

• 트리거: 다음 파일이 변경될 때만 실행됩니다:

doc-locale/ja-jp/**/*.md - 일본어 문서 파일

• doc-locale/ja-jp/.vale.ini - 일본어 Vale 설정

• scripts/i18n_lint_language_vale.sh - 범용 언어 린팅 스크립트

이 job은 환경 변수를 사용하여 범용 스크립트를 설정합니다:

variables:
  LANGUAGE_CODE: "ja-jp"
  LANGUAGE_NAME: "Japanese"

한국어 지원#

docs-i18n-lint korean-vale job은 한국어 전용 Vale 린팅을 실행합니다:

• 스크립트: scripts/i18n_lint_language_vale.sh

• 설정: doc-locale/ko-kr/.vale.ini

• Vale 필터: locale_rules

• 트리거: 다음 파일이 변경될 때만 실행됩니다:

doc-locale/ko-kr/**/*.md - 한국어 문서 파일

• doc-locale/ko-kr/.vale.ini - 한국어 Vale 설정

• scripts/i18n_lint_language_vale.sh - 범용 언어 린팅 스크립트

이 job은 환경 변수를 사용하여 범용 스크립트를 설정합니다:

variables:
  LANGUAGE_CODE: "ko-kr"
  LANGUAGE_NAME: "Korean"

프랑스어 지원#

docs-i18n-lint french-vale job은 프랑스어 전용 Vale 린팅을 실행합니다:

• 스크립트: scripts/i18n_lint_language_vale.sh

• 설정: doc-locale/fr-fr/.vale.ini

• Vale 필터: locale_rules

• 트리거: 다음 파일이 변경될 때만 실행됩니다:

doc-locale/fr-fr/**/*.md - 프랑스어 문서 파일

• doc-locale/fr-fr/.vale.ini - 프랑스어 Vale 설정

• scripts/i18n_lint_language_vale.sh - 범용 언어 린팅 스크립트

이 job은 환경 변수를 사용하여 범용 스크립트를 설정합니다:

variables:
  LANGUAGE_CODE: "fr-fr"
  LANGUAGE_NAME: "French"

새 언어 추가#

추가 언어에 대한 언어별 린팅을 추가하려면:

doc-locale/LANGUAGE_CODE/.vale.ini에 언어별 Vale 설정을 생성합니다.

.gitlab/ci/docs.gitlab-ci.yml에 새 CI job을 추가합니다:

docs-i18n-lint LANGUAGE-vale:
  extends:
    - .default-retry
    - .docs:rules:docs-i18n-lint-LANGUAGE
    - .docs-markdown-lint-image
  stage: lint
  needs: []
  variables:
    LANGUAGE_CODE: "LANGUAGE_CODE"     # e.g., "fr-fr", "de-de"
    LANGUAGE_NAME: "LANGUAGE_NAME"     # e.g., "French", "German"
  script:
    - source ./scripts/utils.sh
    - install_gitlab_gem
    - scripts/i18n_lint_language_vale.sh

.gitlab/ci/rules.gitlab-ci.yml에 트리거 규칙을 추가합니다:

.docs:rules:docs-i18n-lint-LANGUAGE:
  rules:
    - <<: *if-tech-docs-localization
      changes:
        - "doc-locale/LANGUAGE_CODE/**/*.md"
        - "doc-locale/LANGUAGE_CODE/.vale.ini"
        - "scripts/i18n_lint_language_vale.sh"

범용 스크립트 방식은 환경 변수를 통한 언어별 커스터마이징을 유지하면서 코드 중복을 제거합니다.

docs-i18n-lint links 및 기타 job의 테스트#

번역 문서의 끊어진 링크를 검사하기 위해, 번역된 Markdown(.md) 파일 변경을 포함한 머지 리퀘스트는 파이프라인에서 다음 job을 실행합니다:

• gitlab 프로젝트의 docs-i18n-lint links job. 예: https://gitlab.com/gitlab-org/gitlab/-/jobs/7065686331.

• omnibus-gitlab 프로젝트의 docs-i18n-lint links job. 예: https://gitlab.com/gitlab-org/omnibus-gitlab/-/jobs/7065337075.

• gitlab-operator 프로젝트의 docs-i18n-lint links job.

• gitlab-runner 프로젝트의 docs:lint i18n markdown job(링크 검사 포함). 예: https://gitlab.com/gitlab-org/gitlab-runner/-/jobs/7056674997.

• charts/gitlab 프로젝트의 check_docs_i18n_links job. 예: https://gitlab.com/gitlab-org/charts/gitlab/-/jobs/7066011619.

이 job들은 앵커 링크를 포함한 끊어진 링크를 검사합니다. 네트워크 연결이 필요한 링크는 건너뜁니다. 끊어진 링크가 발견되면 job 로그에 나열되지만, job이 파이프라인을 실패시키지는 않습니다. Runner 프로젝트의 docs:lint i18n markdown job을 제외하고 job은 수동으로 시작해야 합니다.

고아 번역 파일의 경로 검증#

docs-i18n-lint paths job은 /doc-locale의 번역 파일에 해당하는 영어 소스 파일이 없으면 실패합니다. 이 job은 다음 경우에 실행됩니다:

• /doc-locale의 파일이 수정될 때

• 경로 검증 스크립트가 변경될 때

고아 번역 파일이 감지되면 현지화 팀원이 필요한 삭제 작업을 처리합니다. 새 번역이 제공될 때까지 영어 대체 콘텐츠가 제공됩니다.

문서 린터 설치#

문서 스타일 가이드라인을 준수하고 문서에 추가되는 콘텐츠를 개선하려면, 문서 린터를 설치하고 코드 에디터와 통합하세요. 최소한 빌드 파이프라인에서 실행되는 검사와 일치하도록 markdownlint와 Vale를 설치하세요. 두 도구 모두 코드 에디터와 통합할 수 있습니다.

로컬에서 문서 테스트 실행#

로컬 실행의 장점은 다음과 같습니다:

• 피드백 루프가 빨라집니다. CI/CD 파이프라인이 실행될 때까지 기다리지 않고 브랜치의 변경 사항 문제를 파악할 수 있습니다.

• 비용이 절감됩니다. 로컬에서 테스트를 실행하는 것이 GitLab이 사용하는 클라우드 인프라에서 테스트를 실행하는 것보다 저렴합니다.

다음 사항이 중요합니다:

• 도구를 최신 상태로 유지하고, CI/CD 파이프라인에서 사용하는 버전과 일치시킵니다.

• CI/CD 파이프라인에서 실행되는 것과 동일한 방식으로 린터, 문서 링크 테스트, UI 링크 테스트를 실행합니다. 도구의 기본 설정과 다를 수 있는 CI/CD 파이프라인에서 사용하는 것과 동일한 설정을 사용하는 것이 중요합니다.

로컬에서 Vale, markdownlint, 또는 링크 검사 실행#

다음에 대한 설치 및 설정 지침이 제공됩니다:

• markdownlint.

• Vale.

• Lychee 및 UI 링크 검사기.

로컬에서 lint-doc.sh 실행#

Rake 태스크를 사용하여 lint-doc.sh 테스트를 로컬에서 실행합니다.

사전 조건:

• 다음 중 하나가 필요합니다:

컴퓨터에 필수 린트 도구가 설치되어 있어야 합니다.

• 이 도구들이 사전 설치된 이미지를 사용하기 위해 Docker 또는 containerd가 작동해야 합니다.

gitlab 디렉터리로 이동합니다.

다음을 실행합니다:

rake lint:markdown

단일 파일이나 디렉터리에 대해서만 린트 검사를 실행하려면 다음을 실행합니다:

MD_DOC_PATH=path/to/my_doc.md rake lint:markdown

출력은 다음과 유사해야 합니다:

=> Linting documents at path /path/to/gitlab as <user>...
=> Checking for cURL short options...
=> Checking for CHANGELOG.md duplicate entries...
=> Checking /path/to/gitlab/doc for executable permissions...
=> Checking for new README.md files...
=> Linting markdown style...
=> Linting prose...
✔ 0 errors, 0 warnings and 0 suggestions in 1 file.
✔ Linting passed

린터 설정 업데이트#

Vale와 markdownlint 설정은 각 프로젝트에서 소스 제어 하에 있으므로, 업데이트는 각 프로젝트에 개별적으로 커밋해야 합니다.

gitlab 프로젝트의 설정을 단일 진실 공급원(Single Source Of Truth, SSOT)으로 취급하고, 모든 업데이트는 먼저 여기서 이루어져야 합니다.

정기적으로 gitlab 프로젝트에서 Vale 및 markdownlint 설정에 대한 변경 사항을 다른 프로젝트에 동기화해야 합니다. 지원되는 각 프로젝트에서:

새 브랜치를 생성합니다. 일부 프로젝트는 실행되는 job을 제한하기 위한 규칙으로 브랜치 이름 앞에 docs-를 추가하거나 끝에 -docs를 붙이는 관례를 사용합니다.

gitlab 프로젝트에서 설정 파일을 복사합니다. 예를 들어, 프로젝트의 루트 디렉터리에서 다음을 실행합니다:

# Copy markdownlint configuration file
cp ../gitlab/.markdownlint-cli2.yaml .
# Remove existing Vale configuration in case some rules have been removed from the GitLab project
rm -r docs/.vale/gitlab
# Copy gitlab_base Vale configuration files for a project with documentation stored in 'docs' directory
cp -r ../gitlab/doc/.vale/gitlab_base docs/.vale

gitlab-runner, gitlab-omnibus, charts/gitlab, 또는 gitlab-operator를 업데이트하는 경우, gitlab 프로젝트에서 gitlab-docs Vale 설정도 복사합니다. 예를 들어, 프로젝트의 루트 디렉터리에서 다음을 실행합니다:

# Copy gitlab-docs Vale configuration files for a project with documentation stored in 'docs' directory
cp -r ../gitlab/doc/.vale/gitlab_docs docs/.vale

.markdownlint-cli2.yaml에 대해 생성된 diff를 검토합니다. 예를 들어 다음을 실행합니다:

git diff .markdownlint-cli2.yaml

필요하지 않은 변경 사항을 제거합니다. 예를 들어, customRules는 gitlab 프로젝트에서만 사용됩니다.

Vale 설정에 대해 생성된 diff를 검토합니다. 예를 들어 다음을 실행합니다:

git diff docs

RelativeLinks.yml에서 불필요한 변경 사항을 제거합니다. 이 규칙은 각 프로젝트에 특화되어 있습니다.

.tmpl 파일을 제거합니다. 이 파일들은 gitlab 프로젝트에서만 사용됩니다.

새 규칙 위반 여부를 확인하기 위해 markdownlint-cli2를 실행합니다. 예를 들어:

markdownlint-cli2 docs/**/*.md

새 규칙 위반 여부를 확인하기 위해 Vale를 실행합니다. 예를 들어:

vale --minAlertLevel error docs

새 브랜치에 변경 사항을 커밋합니다. 일부 프로젝트는 관례적 커밋(conventional commits)을 요구하므로 커밋하기 전에 프로젝트의 기여 정보를 확인하세요.

머지 리퀘스트를 검토를 위해 제출합니다.

린팅 이미지 업데이트#

린트 테스트는 docs-gitlab-com 컨테이너 레지스트리의 이미지를 사용하여 CI/CD 파이프라인에서 실행됩니다.

의존성의 새 버전이 릴리즈되면(예: Vale의 새 버전), 이미지를 업데이트하여 최신 버전을 사용해야 합니다. 그런 다음, 각 문서 프로젝트의 설정 파일을 새 이미지를 가리키도록 업데이트할 수 있습니다.

린팅 이미지를 업데이트하려면:

• docs-gitlab-com에서 새 도구 버전을 사용하도록 .gitlab-ci.yml을 업데이트하는 머지 리퀘스트를 엽니다. (예시 MR)

• 병합되면, Build docker images pipeline (Manual) 예약된 파이프라인을 시작합니다.

• 시작한 파이프라인으로 이동하여 관련 test:image job(예: test:image:docs-lint-markdown)이 완료될 때까지 기다립니다. job이:

통과하면 관련 image: job(예: image:docs-lint-markdown)을 시작합니다.

• 실패하면 테스트 job 로그를 검토하고 문제 해결을 시작합니다. 업데이트된 의존성과 함께 작동하도록 이미지 설정에 일부 수동 조정이 필요할 수 있습니다.

• image: job이 통과하면 job의 로그에서 새 이미지 이름을 확인합니다. (예시 job 출력)

• 새 이미지가 컨테이너 레지스트리에 추가되었는지 확인합니다.

• 새 이미지를 가리키도록 각 설정 파일을 업데이트하는 머지 리퀘스트를 엽니다. markdownlint, vale, 또는 lychee를 사용하는 job의 경우:

gitlab:

.gitlab/ci/docs.gitlab-ci.yml, .docs-markdown-lint-image: 섹션의 image를 업데이트합니다.

• scripts/lint-doc.sh, run_locally_or_in_container() 섹션의 registry_url 값을 업데이트합니다.

• gitlab-runner: .gitlab/ci/_common.gitlab-ci.yml, DOCS_LINT_IMAGE 변수의 값을 업데이트합니다.

• omnibus-gitlab: gitlab-ci-config/variables.yml, DOCS_LINT_IMAGE 변수의 값을 업데이트합니다.

• charts/gitlab: .gitlab-ci.yml, DOCS_LINT_IMAGE 변수의 값을 업데이트합니다.

• cloud-native/gitlab-operator: .gitlab-ci.yml DOCS_LINT_IMAGE 변수의 값을 업데이트합니다.

• gitlab-development-kit: .gitlab-ci.yml DOCS_LINT_IMAGE 변수의 값을 업데이트합니다.

• 각 머지 리퀘스트에서:

이미지를 사용하는 job을 트리거하기 위해 작은 문서 업데이트를 포함합니다.

• 업데이트된 이미지가 테스트에 사용되었는지 확인하기 위해 관련 job 출력을 확인합니다.

• 검토 및 병합을 위해 머지 리퀘스트를 기술 작가에게 할당합니다.

pre-push 훅 설정#

Git pre-push 훅을 통해 Git 사용자는:

• 브랜치를 푸시하기 전에 테스트 또는 기타 프로세스를 실행할 수 있습니다.

• 이 테스트에서 실패가 발생하면 브랜치 푸시를 방지할 수 있습니다.

Lefthook은 Git 훅 관리자입니다. Git 훅의 설정, 설치, 제거를 더 간단하게 만들어 줍니다. 설정은 gitlab 프로젝트의 lefthook.yml 파일에서 확인할 수 있습니다.

문서 린팅을 위해 Lefthook을 설정하려면 Lefthook을 사용한 pre-commit 및 pre-push 정적 분석을 참조하세요.

커밋 또는 푸시 시 Vale 오류를 표시하려면 커밋 또는 푸시 시 Vale 경고 표시를 참조하세요.

문서에서 린팅 비활성화#

일부(전부는 아님) 린팅은 문서 파일에서 비활성화할 수 있습니다:

• Vale 테스트는 파일 전체 또는 일부에 대해 비활성화할 수 있습니다.

• markdownlint 테스트는 파일 전체 또는 일부에 대해 비활성화할 수 있습니다.

CI/CD 파이프라인에서 사용되는 도구 버전#

린팅 규칙과의 최대 호환성을 위해 CI/CD 파이프라인에서 사용하는 것과 동일한 린터 버전을 사용해야 합니다.

GitLab 프로젝트에서 사용되는 markdownlint-cli2 및 vale의 버전을 확인하려면 다음을 참조하세요:

• mise로 관리되는 프로젝트의 경우, 프로젝트의 .tool-versions 또는 mise.toml 파일. 예를 들어:

gitlab 프로젝트의 .tool-versions 파일.

• gitlab-operator 프로젝트의 mise.toml 파일.

• CI/CD용으로 이 도구들을 포함하는 image:docs-lint-markdown Docker 이미지를 빌드할 때 사용되는 버전(variables: 섹션 참조).

이 두 위치에 설정된 버전은 동일해야 합니다.

지원되는 프로젝트#

CI/CD 파이프라인에서 실행되는 각 테스트의 세부 사항은 관련 프로젝트의 설정을 참조하세요:

• https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/docs.gitlab-ci.yml

• https://gitlab.com/gitlab-org/gitlab-runner/-/blob/main/.gitlab/ci/docs.gitlab-ci.yml

• https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/master/gitlab-ci-config/gitlab-com.yml

• https://gitlab.com/gitlab-org/charts/gitlab/-/blob/master/.gitlab-ci.yml

• https://gitlab.com/gitlab-org/cloud-native/gitlab-operator/-/blob/master/.gitlab-ci.yml

• https://gitlab.com/gitlab-org/cli/-/blob/main/.gitlab-ci.yml

다음 프로젝트에서도 일부 문서 테스트를 실행합니다:

• GitLab Development Kit: https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/.gitlab/ci/test.gitlab-ci.yml

• GitLab Docs 웹사이트: https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/blob/main/.gitlab/ci/lint.gitlab-ci.yml

• Gitaly: https://gitlab.com/gitlab-org/gitaly/-/blob/master/.gitlab-ci.yml

• GitLab Duo Plugin for JetBrains: https://gitlab.com/gitlab-org/editor-extensions/gitlab-jetbrains-plugin/-/blob/main/.gitlab-ci.yml

• GitLab for VS Code extension: https://gitlab.com/gitlab-org/gitlab-vscode-extension/-/blob/main/.gitlab-ci.yml

• GitLab Plugin for Neovim: https://gitlab.com/gitlab-org/editor-extensions/gitlab.vim/-/blob/main/.gitlab-ci.yml

• GitLab Language Server: https://gitlab.com/gitlab-org/editor-extensions/gitlab-lsp/-/blob/main/.gitlab-ci.yml

• GitLab for Visual Studio extension: https://gitlab.com/gitlab-org/editor-extensions/gitlab-visual-studio-extension/-/blob/main/.gitlab-ci.yml

• AI Gateway: https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/-/blob/main/.gitlab/ci/lint.gitlab-ci.yml

• Centralized Evaluation Framework: https://gitlab.com/gitlab-org/modelops/ai-model-validation-and-research/ai-evaluation/prompt-library/-/blob/main/.gitlab-ci.yml

• GitLab Container Registry: https://gitlab.com/gitlab-org/container-registry/-/blob/master/.gitlab/ci/validate.yml