validate

콘텐츠 파일의 프론트 매터 완결성, 접근성, 구조 정합성을 검증합니다.

# 모든 콘텐츠 파일 검증
hwaro tool validate

# 특정 콘텐츠 디렉터리 검증
hwaro tool validate -c posts

# 경고도 CI 실패로 처리하거나, 허용 경고 수 상한 지정
hwaro tool validate --strict
hwaro tool validate --max-warnings 5

# JSON으로 출력
hwaro tool validate --json

옵션

플래그	설명
-c, --content-dir DIR	콘텐츠 디렉터리 (기본값: content)
--strict	종료 코드 계산 시 경고를 오류로 취급
--max-warnings N	경고 수가 N을 넘으면 0이 아닌 코드로 종료 (기본값: 무제한)
-j, --json	결과를 JSON으로 출력
-h, --help	도움말 표시

검사 항목

프론트 매터에 title 누락 또는 빈 값 (홈페이지는 비워 둘 수 있음)
프론트 매터에 description 누락
대체 텍스트가 비어 있는 Markdown 이미지(![](url))와 alt 속성이 없는 원시 HTML <img> 요소 (장식용 이미지를 뜻하는 alt=""는 허용). 코드 블록, 인라인 코드, HTML 주석 안은 검사하지 않음
깨진 내부 링크: 빌드가 해석할 수 없는 @/ 경로 (tool check-links와 같이 게시되는 페이지의 정확한 원본 경로만 인정)
프론트 매터 파싱 오류 (TOML/YAML/JSON)
유효하지 않은 날짜 형식
대소문자가 섞인 태그 (예: crystal 대신 Crystal)
초안 파일 (info로 보고)
config.toml에 [[content.schema]]가 있으면 프론트 매터 스키마 위반. 기본 빌드가 게시하는 페이지에 빌드와 같은 검사를 실행하므로 validate와 hwaro build가 같은 위반을 보고합니다. validate는 콘텐츠 디렉터리 옆의 config.toml을 스키마가 선언된 경우에만 읽으며, 잘못된 스키마는 설정 오류 코드(3)로 종료합니다

출력 예시

hwaro: validate content

content/blog/draft.md:
    [warn] Missing description in frontmatter
    [info] File is marked as draft

content/about.md:
    [warn] Image missing alt text: ![](photo.jpg)
    [info] Tag has mixed case: "Crystal" (consider lowercase)

checked: 0 errors, 2 warnings, 2 info

색상 터미널에서는 발견 항목이 hwaro validate 헤딩 아래 ⚠/✗/ℹ 기호로 표시되고, 마지막 줄은 심각도별 색이 입혀진 ✦ checked 결과입니다. 오류 수준 문제가 발견되면 0이 아닌 종료 코드를 반환하므로 CI 게이트로 쓸 수 있습니다.

종료 코드는 hwaro doctor와 같은 규칙을 따릅니다. 오류 수준 발견은 콘텐츠 오류 코드(5)로, --strict/--max-warnings로 인한 경고 기반 실패는 일반 코드(1)로 종료되어 파일 자체의 문제와 게이트 강화로 인한 실패를 구분할 수 있습니다. 두 플래그는 --json 실행에도 동일하게 적용됩니다.

-q/--quiet를 주면 보고서는 출력되지 않지만, 오류와 경고는 각각 파일: 메시지 한 줄로 stderr에 계속 출력되므로 조용한 실행이 실패해도 원인을 알 수 있습니다.

규칙 ID

ID	수준	설명
`content-title-missing`	warning	title이 없거나 비어 있거나 "Untitled"임
`content-description-missing`	warning	description 누락
`content-alt-text-missing`	warning	대체 텍스트가 없는 이미지
`content-internal-link-broken`	warning	깨진 `@/` 내부 링크
`content-date-invalid`	warning	인식할 수 없는 날짜 형식
`content-frontmatter-toml-error`	error	TOML 프론트 매터 파싱 오류
`content-frontmatter-yaml-error`	error	YAML 프론트 매터 파싱 오류
`content-frontmatter-json-error`	error	JSON 프론트 매터 파싱 오류
`content-read-error`	error	콘텐츠 파일 읽기 실패
`content-tag-mixed-case`	info	대소문자가 섞인 태그
`content-draft`	info	초안으로 표시된 파일
`content-schema-violation`	error	프론트 매터가 `[[content.schema]]`를 위반

JSON 출력

{
  "findings": [
    {
      "file": "content/blog/draft.md",
      "line": null,
      "rule": "content-description-missing",
      "severity": "warning",
      "message": "Missing description in frontmatter"
    }
  ]
}

스키마 위반에는 line이 들어갑니다(빠진 필드는 null). [[content.schema]]가 선언되어 있으면 defaults 객체가 파일별로, 빌드가 그 페이지의 빠진 필드에 적용하는 기본값을 나열합니다:

{
  "findings": [],
  "defaults": {
    "content/posts/b.md": { "status": "draft" }
  }
}