HanMark

마크다운으로 한글(한컴오피스) 원고를 쓰는 확장입니다. 겹낫표·낫표 입력, 주석 삽입·자동 정렬, 한컴식 문단 스타일 단축키를 제공하고, 완성된 원고를 한글의 진짜 각주/미주 객체가 담긴 HWPX로 내보냅니다.

설정창

오른쪽 아래 **⚙ HanMark**를 누르면 하단 패널(터미널·문제 탭 옆)에 설정창이 열립니다. 체크박스·드롭다운이 늘 보이는 화면이라 설정 이름을 검색할 필요가 없고, 켠 채로 원고를 쓰면서 그때그때 바꿀 수 있습니다.

명령 팔레트의 **"한글 오피스: 설정 열기"**로도 같은 창이 열립니다. 값은 사용자 설정에 기록되며, 폴더별로 다르게 두려면 창 아래쪽의 설정 화면에서 열기를 쓰세요.

기능

1. 겹낫표 입력 모드

상태바의 「」 버튼 또는 Ctrl+Alt+K로 모드를 전환합니다: 끔 → 자동 → 켬.

• 자동 (Windows 전용): 한글 입력 모드일 때만 변환하고, 영어 모드에서는 원래 괄호가 그대로 입력됩니다. 키를 누르는 순간 Windows IME의 한/영 상태를 읽어 판단합니다(상주 헬퍼 프로세스가 WM_IME_CONTROL로 질의, 지연 수 ms). IME 상태를 읽지 못하면 원래 문자를 입력하는 안전한 폴백으로 동작합니다.
• 켬: IME 상태와 무관하게 항상 변환합니다. macOS·Linux에서는 이 모드를 사용하세요(자동 모드는 순환에서 제외됩니다).
• 자동 괄호 닫기: 기본 괄호처럼 여는 낫표를 입력하면 닫는 낫표가 함께 들어가고 커서가 사이에 놓입니다. 닫는 키를 누르면 바로 뒤의 닫는 낫표를 건너뜁니다. hangulOffice.autoClosingBrackets 설정으로 끌 수 있습니다.
• 텍스트를 선택한 상태에서 여는 괄호 키를 누르면 선택 영역을 괄호 쌍으로 감쌉니다.
• 변환하지 않고 통과시키는 경우(영어 모드 등)에는 VS Code 기본 타이핑에 위임하므로 원래의 []·{} 자동 닫기도 그대로 동작합니다.
• 모드 상태는 재시작 후에도 유지됩니다.

2. 마크다운 주석 (한컴 한글의 주석 워크플로)

마크다운 주석 문법([^n] + 문서 끝 정의)을 관리합니다. 편집 중에는 정의가 문서 끝에 모이지만, HWPX로 내보낼 때 각주(기본) 또는 미주로 출력됩니다 — 각주/미주 구분은 산출물에서 결정되므로 이 문서에서는 편집 단계의 것을 '주석'이라 부릅니다.

번호는 항상 자동으로 정렬됩니다.

• 삽입 시: 새 주석은 커서 위치의 등장 순서에 맞는 번호를 받고, 뒤에 오는 주석 번호는 자동으로 밀립니다. 새 정의도 문서 끝에 붙는 게 아니라 번호순 자리에 들어갑니다.
• 저장 시: 문서 전체 주석 번호를 본문 등장 순서대로 자동 재정렬하고, 정의 블록의 물리적 순서도 번호순으로 맞춥니다. hangulOffice.autoRenumberOnSave 설정으로 끌 수 있습니다.
• 여러 줄 주석(들여쓴 연속 줄)은 블록 통째로 움직이며, 정의 사이에 본문이 끼어 있으면 연속된 정의 묶음 안에서만 정렬해 본문은 건드리지 않습니다.

주의: Ctrl+N, N은 두 단계 코드(chord) 단축키라서, 마크다운 편집기 안에서는 Ctrl+N 단독의 '새 파일' 동작이 코드 대기 상태로 바뀝니다(다른 파일·다른 위치에서는 그대로 동작). 원치 않으면 키보드 단축키 설정에서 hangulOffice.insertFootnote의 Ctrl+N N 바인딩을 제거하세요.

2-1. 문단 스타일 단축키 (Ctrl+숫자)

한컴 한글의 Ctrl+숫자 스타일 전환처럼, 커서가 있는 줄(또는 선택한 여러 줄)의 문단 스타일을 바꿉니다. 마크다운 접두사를 교체하는 방식입니다.

주의: 마크다운 편집기 안에서는 Ctrl+1~Ctrl+8의 VS Code 기본 동작(편집기 그룹 포커스)이 가려집니다. 다른 파일에서는 그대로 동작합니다.

3. HWPX 내보내기

명령 팔레트에서 **"한글 오피스: HWPX로 내보내기"**를 실행하면 현재 마크다운 문서가 같은 이름의 .hwpx로 변환됩니다. 마크다운 주석([^n])은 한글의 진짜 각주 객체로 변환되어, 한컴오피스에서 열면 번호·구분선·페이지 하단 배치가 모두 정상 동작합니다.

그림: 마크다운 이미지 한 줄(느낌표·대괄호·괄호로 쓰는 그 문법)만으로 이루어진 문단은 한글의 그림 객체로 변환됩니다. 원본 파일이 hwpx 안에 담기므로 내보낸 파일 하나만 옮겨도 그림이 유지됩니다. 경로는 마크다운 문서 위치를 기준으로 풀립니다. 폭은 hangulOffice.hwpxImageWidthInch(기본 6인치)로 정하고, 원본이 그보다 좁으면 확대하지 않습니다. 캡션은 그림 바로 다음 문단에 쓰면 됩니다. 파일을 읽지 못하면 [그림 없음: 경로]가 남으므로 빠진 그림을 놓치지 않습니다.

표는 아직 변환하지 않고 마크다운 문법 그대로 출력됩니다.

각주/미주 선택: 기본은 각주(페이지 하단)입니다. hangulOffice.hwpxNoteType 설정을 endnote로 바꾸면 미주(문서 끝, 한글의 미주 객체)로 출력됩니다. 미주의 번호 형식·배치는 템플릿의 미주 설정을 따릅니다.

낫표 반각 변환(선택): 설정창의 낫표·겹낫표 폭에서 전각·반각을 고릅니다(설정 키는 hangulOffice.hwpxHalfwidthBrackets). 반각을 고르면 내보낼 때 본문·주석의 낫표 「」를 ｢｣로, 겹낫표 『』를 한컴 사설 영역의 반각 겹낫표로 바꿔 저장합니다(기본 끔). 마크다운 원문은 전각 그대로 남고 hwpx만 바뀝니다. 반각 겹낫표는 함초롬 계열 글꼴에서만 글리프가 있으므로, 산출물의 글꼴을 그 밖으로 바꿀 생각이면 켜지 마세요. 같은 이유로 마크다운 편집 쪽(입력 모드·반각/전각 일괄 변환)은 낫표를 건드리지 않습니다.

스타일 상속은 선택사항입니다: 아무 설정 없이도 내보내기는 동작합니다. 한컴오피스가 설치되지 않은 환경에서도 내장 기본 스타일 템플릿(확장에 동봉)으로 변환되며, 폰트는 이름만 참조하므로 열람 환경이 알아서 대체합니다. 한컴오피스에서 기본 스타일을 바꿔 쓰고 있고 그 스타일을 물려받고 싶을 때만, 새 문서를 빈 채로 저장한 파일을 hangulOffice.hwpxTemplate 설정에 지정하세요. 생성 문서가 한컴에서 직접 타이핑한 것과 같은 모양이 됩니다.

저장 시 자동 내보내기: hangulOffice.exportHwpxOnSave를 켜면 마크다운을 저장할 때마다 같은 이름의 hwpx가 자동 갱신됩니다(기본 끔). hwpx는 단방향 생성물이므로 hwpx 쪽에서 고친 내용은 다음 내보내기 때 덮어써집니다. 한컴오피스에서 그 파일을 열어둔 상태면 잠금 때문에 내보내기가 실패할 수 있습니다.

변환 범위(1차): 문단, 제목(#~ → 개요 1~), 인용문(> → 템플릿의 인용문 스타일, 없으면 바탕글), 주석(각주/미주). 그 밖의 마크다운 문법(굵게·목록·표 등)은 문자 그대로 들어갑니다.

4. 원고지 분량

마크다운 문서를 열면 상태바에 200자 원고지 매수가 실시간으로 표시됩니다. 단순 글자수 나누기가 아니라 실제 원고지 규칙(문단마다 새 줄 시작, 문단 첫 칸 들여쓰기, 20자×10줄)을 시뮬레이션한 값이고, 주석 내용도 분량에 포함합니다. 텍스트를 선택하면 선택 영역 기준으로 바뀝니다. 상태바 항목을 클릭하면 글자 수(공백 포함/제외)·어절 수 상세가 표시됩니다. hangulOffice.showManuscriptCount로 끌 수 있습니다.

5. 한글 줄바꿈 단위 (글자/어절)

명령 팔레트의 **'한글 줄바꿈 단위'**로 마크다운 문서의 자동 줄바꿈을 글자 단위(기본)와 어절 단위 중에서 고릅니다.

VS Code는 기본 줄바꿈 계산기에서 "글자 단위로 끊어도 되는 문자"를 가나(U+3040~30FF)와 한자(U+3400~4DBF, U+4E00~9FFF)로만 한정합니다. 한글 음절(U+AC00~D7A3)은 그 범위 밖이라 라틴 문자처럼 취급되어, 한자는 글자 단위로 끊기는데 한글만 어절 단위로 끊기는 어긋남이 생깁니다. 확장이 줄바꿈 알고리즘 자체에 끼어들 수는 없으므로, 계산을 브라우저에 위임하는 editor.wrappingStrategy: advanced로 바꿔 CSS 줄바꿈 규칙이 적용되게 합니다.

• editor.wordWrap·editor.wordBreak는 마크다운 언어 범위("[markdown]")에만 기록되므로 코드 파일의 줄바꿈은 그대로입니다.
• editor.wrappingStrategy는 언어별 재정의를 지원하지 않아 전역에 기록됩니다. 아주 긴 줄에서는 simple보다 느릴 수 있습니다.
• 확장이 설정 파일을 고치는 게 싫으면 hangulOffice.koreanLineBreak를 관리 안 함으로 두세요.

6. 반각/전각 일괄 변환 (영숫자·문장부호)

명령 팔레트의 **'반각/전각 일괄 변환'**으로 선택 영역(없으면 문서 전체)의 영숫자·문장부호 폭을 바꿉니다. 영인본 OCR 결과나 일본어권 자료를 옮겨 붙일 때 섞여 들어온 전각 문자를 정리하는 용도입니다.

• 한글·한자는 어느 방향에서도 건드리지 않습니다.
• 반각 공백은 전각 공백으로 바꾸지 않습니다 — 마크다운의 들여쓰기·목록 문법이 깨지기 때문입니다. 반대로 전각 공백(U+3000)은 반각으로 정리합니다.
• 문서 전체를 전각으로 바꾸면 마크다운 문법 기호(#, *, [, ])까지 바뀌므로 실행 전에 한 번 확인합니다.

낫표·겹낫표는 왜 다루지 않나

낫표·겹낫표는 입력에서도 변환에서도 전각만 씁니다. 검토 끝에 반각을 아예 넣지 않기로 했고, 이유는 이렇습니다.

• 겹낫표 『』에는 반각 대응 문자가 없습니다. 유니코드 Halfwidth and Fullwidth Forms 블록(U+FF61~FF65)에는 낫표(corner bracket)만 있고, 흰 낫표(white corner bracket)의 반각형은 정의된 적이 없습니다.
• 그래서 낫표만 반각(｢｣)으로 바꾸면 「논문 제목」과 『잡지명』을 나란히 쓰는 원고에서 폭이 짝짝이가 됩니다.
• 한컴오피스는 HNC 문자표의 반각 겹낫표를 사설 사용 영역(U+F0854·U+F0855)에 배정해 제공하지만, 표준 문자가 아니라 글리프를 가진 폰트가 함초롬바탕·함초롬돋움뿐입니다. 그 폰트가 없는 PC·웹·다른 편집기에서는 폴백할 대상 자체가 없어 무조건 두부(□)로 보입니다.
• 폰트를 확장에 내장해 해결할 수도 없습니다. 함초롬체는 사용은 자유롭지만 파일의 수정·재배포·유료 판매가 금지돼 있어 .vsix에 실어 배포할 수 없고, 애초에 VS Code는 확장이 편집기 본문 폰트를 공급하는 API를 제공하지 않습니다.

즉 어느 경로로도 주고받을 수 있는 결과가 나오지 않습니다.

알려진 제한 (베타)

• 주석 기능은 마크다운 파일에서만 활성화됩니다. Pandoc footnote 문법([^n])을 따릅니다.
• 코드 블록 안의 [^n] 표기도 주석으로 간주합니다(추후 개선 예정).
• 겹낫표 '자동' 모드는 Windows 전용입니다. macOS는 IME 상태를 읽는 공개 API 구조가 달라 '켬' 모드를 사용해야 합니다.
• 줄바꿈 단위는 확장이 편집기 설정을 대신 기록하는 방식입니다. VS Code가 확장에 줄바꿈 계산 자체를 여는 API를 제공하지 않기 때문이며, 설정을 직접 고치면 그 값이 우선합니다.

로드맵

• 문단 첫 줄 들여쓰기, 쪽 나누기 등 한컴 스타일 편집 명령
• 코드 블록 제외 주석 파싱
• 사용자 정의 괄호 쌍 설정

라이선스

MIT