Hongdown

스타일 규칙 자동 적용

제목은 1·2단계가 Setext 스타일(=== 또는 — 밑줄)이고 3단계 이상은 ATX 스타일(###, ####)을 사용합니다. 정렬(ordered) 목록은 1. 형식을, 비정렬(unordered) 목록은 ‘ – ‘ (공백-하이픈-공백 두 개) 형식을 사용하며, 중첩 항목은 4칸 들여쓰기를 적용합니다. 코드 블록은 네 개의 물결표(~~~~)로 펜싱하고, 외부 코드 포맷터를 연결해 임베디드 코드를 언어별 도구로 정렬할 수 있습니다.

문장 형식 및 표기 변환

구두점을 타이포그래피 규칙에 맞춰 자동으로 변환합니다. 큰따옴표·작은따옴표·줄임표는 곡선 부호로 바뀌고, 기본적으로 em dash(–)도 처리됩니다. 동아시아 와이드 문자는 표시 칸 2칸으로 계산하여 약 80칸에서 줄 바꿈이 이루어지며, 너무 긴 단어는 분리되지 않고 그대로 유지됩니다.

링크, 표, 수식 처리

외부 URL은 레퍼런스 스타일 링크로 변환되어 각 섹션 끝에 참조가 배치되고, 상대/로컬 URL은 인라인으로 유지됩니다. 표는 파이프 정렬 시 동아시아 와이드 문자 폭을 고려해 최소 열 너비를 보장합니다. 인라인($…$) 및 디스플레이($$…$$) TeX/LaTeX 수식은 그대로 보존되며, GitHub의 달러-수식 파싱 규칙을 따릅니다.

MDX 모드

.mdx 확장자는 자동으로 MDX 모드를 활성화하여 임베디드 JS/JSX를 그대로 보존하고 주변 마크다운 prose만 포맷합니다. .md 입력이나 stdin에서는 –mdx 옵션 또는 mdx = true 설정으로 활성화할 수 있습니다.

문장 케이스 변환

설정에서 sentence_case = true를 켜면 제목이 자동으로 문장 케이스로 변환됩니다. 첫 단어만 대문자화하고, 백틱 코드 스팬과 2글자 이상 연속 대문자 약어(API, HTTP 등)는 보존하며, 하이픈 단어, 인용부호 안의 대소문자, CJK 등 비라틴 문자도 그대로 유지됩니다. 문서별로 proper_nouns와 common_nouns을 HTML 주석 지시문으로 정의해 동작을 미세 조정할 수 있습니다.

HTML 주석 지시문

특정 파일, 줄, 섹션의 포맷팅을 끄거나 다시 켤 수 있습니다. hongdown-disable-file로 파일 전체, hongdown-disable-next-line으로 다음 한 줄, hongdown-disable-next-section으로 다음 h1/h2까지의 영역을 보존할 수 있습니다. hongdown-proper-nouns와 hongdown-common-nouns 지시문은 설정 파일 설정과 합쳐져 적용됩니다.

설치·시작·기본 사용

Windows에서는 winget으로 설치할 수 있습니다. 설치 후 hongdown 명령으로 입력 파일을 포맷하거나 –write(-w) 옵션으로 파일을 직접 수정할 수 있고, –check(-c)나 –diff(-d) 옵션으로 검사 또는 변경점 비교가 가능합니다. 표준 입력은 –stdin 플래그 또는 파일명을 – 로 지정해 처리할 수 있으며, –line-width 또는 –no-line-width로 줄 너비를 조정할 수 있습니다.

• winget: winget install HongMinhee.Hongdown
• Scoop: scoop bucket add extras 후 scoop install hongdown
• npm: npm install -g hongdown
• mise: mise use -g aqua:dahlia/hongdown
• Nix: nix run github:dahlia/hongdown
• cargo: cargo install hongdown

설정 파일

설정은 시스템, 사용자 레거시, 사용자 플랫폼별, 프로젝트 순으로 누적되어 적용되며, 우선순위가 높은 설정이 낮은 설정을 덮어씁니다. –config 옵션으로 캐스케이딩을 우회해 특정 파일만 사용할 수 있고, no_inherit = true로 시스템·사용자 설정을 무시할 수 있습니다. include 패턴을 지정하면 hongdown –write, hongdown –check 형태로 파일 인자 없이도 동작합니다.

에디터 통합

Visual Studio Code에서는 Hongdown 확장을 설치해 Markdown과 MDX의 기본 포맷터로 지정할 수 있으며, 기본적으로 번들된 WebAssembly 빌드를 사용합니다. 필요 시 hongdown.backend를 cli로 설정해 시스템 Hongdown CLI를 사용할 수 있습니다. Zed, Neovim(none-ls.nvim), Helix에서도 hongdown 명령을 외부 포맷터로 등록해 연동할 수 있습니다.

라이브러리 사용

Rust에서는 hongdown 크레이트의 format 함수와 Options 구조체를 사용해 마크다운 문자열을 포맷할 수 있습니다. JavaScript/TypeScript에서는 @hongdown/wasm을 설치해 format, formatWithWarnings, loadConfigFromToml 등의 API를 호출할 수 있으며, CLI의 code_block.formatters에 해당하는 외부 포맷터 설정은 WASM 런타임에서는 경고로만 보고됩니다.

활용 예시

• 여러 마크다운 파일을 한 번에 정돈된 스타일로 통일하기 위해 hongdown -w *.md 또는 hongdown -w docs/ 형태로 재귀 포맷팅을 수행합니다.
• CI에서 hongdown –check로 스타일 위반 여부를 검사하고 위반 시 비정상 종료(exit 1)로 빌드를 실패 처리합니다.
• Hongdown 확장을 에디터에 설치해 저장 시점에 자동으로 마크다운이 정리되도록 하고, hongdown-no-format 지시문으로 외부 포맷터가 손대지 말아야 할 코드 블록을 보호합니다.
• 문서 전반의 제목 표기를 문장 케이스로 통일하기 위해 설정에서 sentence_case = true를 켜고, 도메인 고유 명사는 proper_nouns에 추가합니다.

제한·라이선스·확인사항

Hongdown은 GPL-3.0-orlater 라이선스로 배포됩니다. 외부 코드 포맷터는 CLI 모드에서만 동작하며, WASM 빌드에서는 code_block.formatters 설정이 경고로만 보고됩니다. 0.4.3부터 사전 빌드 압축 파일은 평면 레이아웃으로 제공되어 추가 최상위 디렉터리 없이 압축 해제됩니다.