convert

콘텐츠 파일 전체의 프론트 매터를 TOML, YAML, JSON 형식 간에 변환합니다.

# 모든 프론트 매터를 YAML로 변환
hwaro tool convert to-yaml

# 모든 프론트 매터를 TOML로 변환
hwaro tool convert to-toml

# 모든 프론트 매터를 JSON으로 변환
hwaro tool convert to-json

# 특정 디렉터리만 변환
hwaro tool convert to-yaml -c content/posts

# 아무것도 바꾸지 않고 어떤 파일이 변환될지 미리보기
hwaro tool convert to-yaml --dry-run

# 결과를 JSON으로 출력
hwaro tool convert to-yaml --json

이 명령은 형식 인자(to-yaml, to-toml, to-json) 하나만 받습니다. 추가 위치 인자는 오류로 거부되므로 다른 옵션은 --content-dir 같은 플래그를 사용하세요.

옵션

변환은 파일을 제자리에서 다시 쓰며 프론트 매터 주석을 보존할 수 없으므로, 중요한 트리에는 --dry-run을 먼저 실행하세요. 파일을 쓰지 않을 뿐 파일별 "dropping N comment line(s)" 경고를 포함한 전체 파이프라인이 동일하게 동작합니다.

TOML에는 null이 없으므로 to-toml은 YAML/JSON의 null 값을 빌드가 같은 의미로 읽는 형태로 씁니다. title, description, slug, image, date 같은 기본 키 (값 없이 끝나는 description:, slug: ~, "image": null)는 키를 생략합니다. 빈 문자열을 쓰면 제목이나 slug가 빈 값으로 설정되기 때문입니다. 섹션의 [cascade]가 설정할 수 있는 키(draft, tags, template 등), extra 값, 사용자 정의 키는 ""가 됩니다. 이런 키는 null이어도 선언된 것으로 취급되어 캐스케이드를 계속 막고, 빌드는 null 사용자 정의 값을 이미 빈 문자열로 읽습니다.

JSON 출력

{
  "success": true,
  "message": "Converted 5 files to YAML",
  "converted_count": 5,
  "skipped_count": 2,
  "error_count": 0,
  "dry_run": false
}

건너뛴 파일

사람이 읽는 요약에는 건너뛴 개수가 이유별(already TOML, without front matter, not front matter)로 나뉘어 표시됩니다.

converted: 5 files · 2 skipped (1 already TOML, 1 not front matter)

이 중 not front matter를 눈여겨보세요. 파일 첫머리의 ---/+++ 쌍 안이 키/값 매핑이 아니라 본문(예: 수평선)이라는 뜻입니다. 그대로 변환하면 작성자의 글이 지워지므로 파일을 건드리지 않고 stderr에 파일명을 남깁니다.

예시

변환 전:

+++
title = "My Post"
date = "2024-01-15"
tags = ["crystal", "tutorial"]
+++

Content here.

hwaro tool convert to-yaml 실행 후:

---
title: My Post
date: "2024-01-15"
tags:
- crystal
- tutorial
---

Content here.

hwaro tool convert to-json 실행 후:

{
  "title": "My Post",
  "date": "2024-01-15",
  "tags": [
    "crystal",
    "tutorial"
  ]
}

Content here.