Vale는 영어의 문법, 스타일, 단어 사용을 검사하는 린터입니다. Vale의 구성은 프로젝트 루트 디렉터리에 있는 .vale.ini 파일에 저장됩니다. 예를 들어 gitlab 프로젝트의 .vale.ini가 있습니다.

Vale은 여러 유형의 검사를 확장하는 커스텀 규칙을 생성할 수 있으며, 이러한 규칙은 프로젝트의 문서 디렉터리에 저장됩니다. 예를 들어 gitlab 프로젝트의 doc/.vale 디렉터리가 있습니다.

이 구성은 빌드 파이프라인에서도 사용되며, 오류 수준 규칙이 적용됩니다.

Vale을 사용할 수 있는 환경:

• 커맨드 라인.

• 코드 에디터.

• Git 훅. Vale은 Git 훅에서 오류만 보고하며(CI/CD 파이프라인과 동일한 구성), 제안이나 경고는 보고하지 않습니다.

Vale 설치#

다음 방법 중 하나를 사용하여 vale를 설치합니다:

• mise. 예:

  mise use -g vale
  

• 패키지 매니저:

  macOS에서 brew를 사용하는 경우: brew install vale.

  • Linux의 경우 배포판의 패키지 매니저 또는 릴리스된 바이너리를 사용합니다.

에디터에서 Vale 구성#

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

에디터에서 Vale을 구성하려면 적절한 다음 도구 중 하나를 설치합니다:

• Visual Studio Code ChrisChinchilla.vale-vscode 확장. 플러그인을 구성하여 알림의 일부만 표시할 수 있습니다.

• Sublime Text SublimeLinter-vale 패키지. Vale의 제안이 오류처럼 빨간색 대신 파란색으로 표시되게 하려면, SublimeLinter 구성에 vale 구성을 추가합니다:

  "vale": {
    "styles": [{
      "mark_style": "outline",
      "scope": "region.bluish",
      "types": ["suggestion"]
    }]
  }
  

• Sublime Text용 LSP 패키지 LSP-vale-ls.

• Vim ALE 플러그인.

• JetBrains 플러그인.

• Emacs Flycheck 확장. Flycheck가 Vale과 함께 작동하기 위한 최소한의 구성은 다음과 같습니다:

  (flycheck-define-checker vale
    "A checker for prose"
    :command ("vale" "--output" "line" "--no-wrap"
              source)
    :standard-input nil
    :error-patterns
      ((error line-start (file-name) ":" line ":" column ":" (id (one-or-more (not (any ":")))) ":" (message)   line-end))
    :modes (markdown-mode org-mode text-mode)
    :next-checkers ((t . markdown-markdownlint-cli))
  )
  
  (add-to-list 'flycheck-checkers 'vale)
  

이 설정에서 markdownlint 검사기는 정의된 vale 검사기의 "next" 검사기로 설정됩니다. 이 커스텀 Vale 검사기를 활성화하면 Vale과 markdownlint 모두에서 오류 린팅이 제공됩니다.

결과 유형#

Vale은 세 가지 유형의 결과를 반환합니다:

• 오류(Error) - 브랜딩 가이드라인, 상표 가이드라인, 문서 사이트에서 콘텐츠가 올바르게 렌더링되지 않게 하는 모든 항목에 해당합니다.

• 경고(Warning) - 일반적인 스타일 가이드 규칙, 원칙, 모범 사례에 해당합니다.

• 제안(Suggestion) - 문서의 리팩토링 또는 예외 목록 업데이트가 필요할 수 있는 기술 문서 작성 스타일 선호도에 해당합니다.

결과 유형에는 다음과 같은 속성이 있습니다:

새 Vale 규칙을 추가하는 시점#

모든 스타일 가이드 규칙에 Vale 규칙을 추가하고 싶은 유혹이 있을 수 있습니다. 그러나 Vale 규칙을 만들고 적용하는 데 드는 노력과 그로 인해 발생하는 노이즈를 염두에 두어야 합니다.

일반적으로 다음 가이드라인을 따릅니다:

• 오류 수준 Vale 규칙을 추가하는 경우, 규칙을 추가하기 전에 문서에서 기존 문제를 모두 수정해야 합니다.

  단일 머지 리퀘스트에서 수정하기에 너무 많은 문제가 있다면, 규칙을 warning 수준으로 추가합니다. 그런 다음 후속 머지 리퀘스트에서 기존 문제를 수정합니다. 문제가 모두 수정되면 규칙을 error로 승격합니다.

• 경고 수준 또는 제안 수준 규칙을 추가하는 경우 다음을 고려합니다:

  Vale 출력에서 얼마나 많은 추가 경고나 제안이 생성되는지. 추가 경고 수가 상당하다면 규칙이 너무 광범위할 수 있습니다.

  • 문맥에서 허용 가능하기 때문에 작성자가 규칙을 무시할 가능성이 얼마나 되는지. 규칙이 너무 주관적이면 적절히 적용할 수 없고 불필요한 추가 경고를 생성합니다.

  • GitLab UI의 머지 리퀘스트 diff에 표시하는 것이 적절한지. 규칙을 머지 리퀘스트에서 직접 구현하기 어렵다면(예: 페이지 리팩토링이 필요한 경우), 로컬 에디터에서만 표시되도록 제안 수준으로 설정합니다.

새 Vale 규칙을 추가하는 위치#

새 Vale 규칙은 두 가지 범주(Vale에서 스타일로 알려진) 중 하나에 속합니다. 이러한 규칙은 프로젝트의 .vale.ini 파일에 지정된 특정 스타일 디렉터리에 별도로 저장됩니다. 예를 들어 gitlab 프로젝트의 .vale.ini가 있습니다.

새 규칙을 추가할 위치는 제안하는 규칙 유형에 따라 다릅니다:

• gitlab_base: 모든 GitLab 문서에 적용 가능한 기본 규칙.

• gitlab_docs: https://docs.gitlab.com에 게시되는 문서에만 적용 가능한 규칙.

대부분의 새 규칙은 gitlab_base에 속합니다.

실행할 테스트 제한#

Visual Studio Code에서 파일을 볼 때 Vale 알림의 일부만 표시하도록 설정할 수 있습니다:

• Preferences > Settings > Extensions > Vale로 이동합니다.

• Vale CLI: Min Alert Level에서 파일에 표시할 최소 알림 수준을 선택합니다.

커맨드 라인에서 Vale을 실행할 때 Vale 알림의 일부만 표시하려면, error, warning, 또는 suggestion을 허용하는 --minAlertLevel 플래그를 사용합니다. 필요한 경우 --config와 함께 사용하여 프로젝트의 구성 파일을 지정합니다:

vale --config .vale.ini --minAlertLevel error doc/**/*.md

플래그를 생략하면 suggestion 수준 알림을 포함하여 모든 알림이 표시됩니다.

한 번에 하나의 규칙 테스트#

커맨드 라인에서 Vale을 실행할 때 단일 규칙만 테스트하려면, 이 명령을 수정하여 OutdatedVersions를 규칙 이름으로 대체합니다:

vale --no-wrap --filter='.Name=="gitlab_base.OutdatedVersions"' doc/**/*.md

Vale 테스트 비활성화#

문서의 특정 부분에 대해 특정 Vale 린팅 규칙 또는 모든 Vale 린팅 규칙을 비활성화할 수 있습니다:

• 특정 규칙을 비활성화하려면, 텍스트 앞에 <!-- vale gitlab_<type>.rulename = NO --> 태그를 추가하고 텍스트 뒤에 <!-- vale gitlab_<type>.rulename = YES --> 태그를 추가합니다. 여기서 rulename은 GitLab 스타일 중 하나의 디렉터리에 있는 테스트 파일 이름으로 대체합니다.

• 모든 Vale 린팅 규칙을 비활성화하려면, 텍스트 앞에 <!-- vale off --> 태그를 추가하고 텍스트 뒤에 <!-- vale on --> 태그를 추가합니다.

가능하면 문제가 있는 규칙과 줄만 제외합니다.

Vale 범위 규칙에 대한 자세한 정보는 Vale의 문서를 참조하세요.

raw 범위를 사용하는 Vale 규칙을 비활성화하기 위한 임시 해결 방법#

일반적으로 raw 범위를 가진 Vale 규칙을 비활성화할 수 없습니다.

그러나 변경으로 인해 거짓 양성(false positive) 때문에 Vale이 실패하는 경우, 변경 주변의 형식을 조정하여 우회할 수 있습니다. 예를 들어, 거짓 양성이 있는 줄의 시작 부분에 추가 공백을 넣는 방법이 있습니다. 페이지가 계속 정상적으로 렌더링되는지 테스트하고, 특별한 형식의 이유를 설명하는 HTML 주석을 추가합니다.

예를 들어(실제 예시에서 가져온 것):

<!--
The following codeblock uses extra spaces to avoid the Vale ReferenceLinks test.
Do not remove the two-space nesting.
-->

  - [Use a reference-style link that's normally prohibited][1]

  [1]: https://example.com/

자세한 정보는 이 Vale 이슈를 참조하세요.

커밋 또는 푸시 시 Vale 경고 표시#

기본적으로 Lefthook의 Vale 검사는 오류 수준 문제만 표시합니다. 기본 브랜치에는 Vale 오류가 없으므로, 여기에 나열된 오류는 브랜치에 커밋하여 발생한 것입니다.

Vale 경고도 함께 보려면 로컬 환경 변수를 설정합니다: VALE_WARNINGS=true.

커밋 또는 푸시 시 Vale 경고를 활성화하면 문서 모음을 개선하는 데 도움이 됩니다:

• 커밋으로 도입할 수 있는 경고를 탐지할 수 있습니다.

• 페이지에 이미 존재하는 경고를 식별하고, 이를 해결하여 기술적 부채를 줄일 수 있습니다.

이러한 경고는:

• 커밋이 작동하는 것을 중단시키지 않습니다.

• 파이프라인 실패를 유발하지 않습니다.

• 커밋으로 도입된 경고만이 아니라 파일의 모든 경고를 포함합니다.

Lefthook으로 Vale 경고를 활성화하려면:

• 자동으로 활성화: 셸 구성에 VALE_WARNINGS=true를 추가합니다.

• 수동으로 활성화: lefthook 호출 앞에 VALE_WARNINGS=true를 붙입니다. 예:

  VALE_WARNINGS=true bundle exec lefthook run pre-commit
  

또한 Vale 경고를 표시하도록 에디터를 구성할 수 있습니다.

Vale이 식별한 문제 해결#

철자 테스트#

Vale이 유효한 단어를 철자 오류로 표시하면, 다음 가이드라인에 따라 수정할 수 있습니다:

대문자(약어) 테스트#

Uppercase.yml 테스트는 모든 대문자로 된 단어의 잘못된 사용을 검사합니다. 예를 들어, This is NOT important와 같은 사용을 피합니다.

단어가 반드시 모두 대문자로 표기되어야 하는 경우, 다음 가이드라인을 따릅니다:

가독성 점수#

ReadingLevel.yml에서, 우리는 문서의 가독성을 결정하기 위해 Flesch-Kincaid 학년 수준 테스트를 구현했습니다.

일반적인 가이드라인으로, 점수가 낮을수록 문서의 가독성이 높습니다. 예를 들어, 일련의 변경 전에 12였던 페이지가 변경 후 9가 되면, 가독성이 반복적으로 개선된 것을 나타냅니다. 점수는 정확한 과학이 아니지만 페이지의 전반적인 복잡도를 나타내는 데 도움이 됩니다.

가독성 점수는 문장당 단어 수와 단어당 음절 수를 기반으로 계산됩니다. 자세한 정보는 Vale 문서를 참조하세요.

Vale 결과를 파일로 내보내기#

모든(또는 필터링된) Vale 결과를 파일로 내보내려면 이 명령을 수정합니다:

# Returns results of types suggestion, warning, and error
find . -name '*.md' | sort | xargs vale --minAlertLevel suggestion --output line > ../../results.txt

# Returns only warnings and errors
find . -name '*.md' | sort | xargs vale --minAlertLevel warning --output line > ../../results.txt

# Returns only errors
find . -name '*.md' | sort | xargs vale --minAlertLevel error --output line > ../../results.txt

이러한 결과는 해커톤을 위한 문서 관련 이슈 생성에 활용할 수 있습니다.

로컬에서 커스텀 규칙 활성화#

Vale 3.0 이상에서는 두 위치에서 규칙을 사용할 수 있습니다. 이 변경으로 프로젝트에 포함된 규칙과 함께 자체 커스텀 규칙을 만들고 사용할 수 있습니다.

macOS에서 커스텀 규칙을 로컬로 만들고 사용하려면:

• Vale의 Application Support 폴더에 로컬 파일을 생성합니다:

  touch ~/Library/Application\ Support/vale/.vale.ini
  

• 방금 만든 .vale.ini 파일에 다음 줄을 추가합니다:

  [*.md]
  BasedOnStyles = local
  

• ~/Library/Application Support/vale/styles/local 폴더가 없으면 생성합니다:

  mkdir ~/Library/Application\ Support/vale/styles/local
  

• 원하는 규칙을 ~/Library/Application Support/vale/styles/local에 추가합니다.

local 스타일 디렉터리의 규칙은 Vale 결과에서 gitlab 대신 local로 접두사가 붙습니다:

$ vale --minAlertLevel warning doc/ci/yaml/index.md

 doc/ci/yaml/index.md
    ...[snip]...
 3876:17   warning  Instead of future tense 'will   gitlab.FutureTense
                    be', use present tense.
 3897:26   error    Remove 'documentation'          local.new-rule

✖ 1 error, 5 warnings and 0 suggestions in 1 file.

관련 주제#

• Vale의 스타일

• 적용 가능한 규칙이 포함된 예시 스타일