HWPX 변환기 사용법

주소: https://tools.osh.ai.kr/hwpx/convert/

원고(마크다운 또는 Google Docs)를 한글 보고서 서식이 입혀진 .hwpx 파일로 바꿔 준다. 챕터별로 내려받거나, 전체 HWPX로 챕터 목록 순서대로 합친 보고서를 한 번에 내려받을 수 있다.

1. 전체 흐름

  ①  AI 로 원고 작성  ─────────────────►  .md 파일
      (아래 3장의 규칙·프롬프트대로)
                                             │
                    ┌────────────────────────┴────────────────────────┐
                    │                                                 │
      ② Google Drive 에 올려 Google 문서로 변환            ②' 사이트에 .md 파일 직접 업로드
         (공동 검토·수정이 필요할 때)                          (혼자 빠르게 뽑을 때)
                    │                                                 │
                    ▼                                                 │
      ③ 폴더를 서비스 계정에 공유 → 사이트에서 [전체 동기화]           │
                    │                                                 │
                    └────────────────────────┬────────────────────────┘
                                             ▼
                                  ④ 미리보기로 확인
                                             ▼
                                  ⑤ [HWPX ↓] 로 내려받아 한글에서 열기

질문에 대한 답: 두 경로 다 된다.

원고를 확정해서 바로 한글 파일만 뽑을 거면 ②' 가 제일 간단하다. 여러 사람이 장을 나눠 쓰고 계속 고칠 거면 ②③ 경로를 쓴다.

.md 를 Google 문서로 만드는 방법

둘 중 아무거나.

• 파일 업로드: .md 파일을 Drive 에 올린 뒤, 그 파일에서 오른쪽 클릭 → 연결 프로그램 → Google 문서. 제목·표·굵게가 살아난 문서가 새로 만들어진다.
• 붙여넣기: Google 문서에서 도구 → 환경설정 → Markdown 사용 설정 을 켜 두고, 빈 문서에 마크다운 원문을 그대로 붙여넣는다.

만들어진 Google 문서에서 제목 1/제목 2 스타일이 제대로 붙었는지 꼭 확인할 것. 그냥 굵은 글씨로만 들어가 있으면 사이트가 장을 못 나눈다.

2. 사이트 사용 순서

1. 프로젝트 만들기 — https://tools.osh.ai.kr/hwpx/ 에서 보고서 이름으로 하나 만든다.

2. (Docs 경로만) 폴더 공유 — Drive 에 이 보고서용 폴더를 만들고, 아래 계정에 뷰어로 공유한 뒤 폴더 링크를 사이트에 등록한다.

   pdf-reader@gen-lang-client-0908189825.iam.gserviceaccount.com
   

   (화면에도 같은 주소가 적혀 있다. 그 화면의 값이 항상 맞다.) 폴더 등록 후 프로젝트 상단이나 프로젝트 목록의 Google Drive 폴더 열기 ↗ 버튼을 누르면 등록한 폴더가 새 탭으로 열린다.

3. 챕터 분할 기준 정하기 — 한 문서에 보고서 전체가 들어 있으면 어느 제목 수준에서 자를지 고른 뒤 저장한다.

   • 분할 안 함 (문서 전체) : 제목 수준과 관계없이 문서 하나를 통째로 미리보기·페이지 보기·다운로드한다.
   • 제목 1 : 장별 문서 여러 개를 폴더에 넣는 보통의 경우
   • 제목 2 / 제목 3 : 긴 문서 하나를 절 단위로 쪼갤 때. 이때 잘린 조각의 제목 수준이 자동으로 올라간다 (선택한 수준 → 장).
   • 기준을 바꾼 뒤 기존 Google 문서는 다시 동기화한다. 업로드 문서는 원본 파일을 다시 올린다. 기존 업로드 챕터는 자동으로 합쳐지거나 삭제되지 않으므로, 새 결과 확인 후 필요 없는 챕터를 정리한다.

4. 가져오기 — [전체 동기화](폴더 전체) / [문서 추가](개별 Doc 링크) / [.md 업로드] 중 하나.

   • 동기화는 마지막 동기화 이후 수정된 문서만 다시 가져온다.
   • Docs 를 고쳤으면 그 챕터 줄의 ⟳ 만 눌러도 된다.

5. 미리보기 — 챕터 제목을 누르면 변환 결과가 보인다. 페이지 보기는 A4 조판·각주 위치까지 실제와 비슷하게 보여 준다. 기본 너비 맞춤은 본문을 화면 폭에 맞춰 확대한다. 한 페이지 맞춤은 한 장 전체를 화면에 보여 주며, **− / +**로 확대 비율을 조절하고 **100%**로 되돌릴 수 있다. 목차 접기를 누르면 본문 영역이 더 넓어진다. 왼쪽 목차에서 제목 1~5를 펼치거나 접고, 제목을 눌러 해당 위치로 이동할 수 있다. Google Docs 챕터는 페이지 보기 상단의 재동기화로 다시 가져올 수 있다. 완료 후 같은 페이지 보기로 돌아온다. 위쪽에 ⚠ 경고가 뜨면 무엇이 빠졌는지 알려 주는 것이다 (5장 참조).

6. 내려받기 — [HWPX ↓]. 파일명은 001_Ⅱ. 연구 내용.hwpx 처럼 순서번호가 붙는다. 본문·제목·표 안·표/그림 제목의 각주는 HWPX의 각주로 유지된다. 각주 번호는 문서 순서대로 이어지며, 전체 HWPX에서도 챕터 사이에 연속된다. 챕터 표 머리글 오른쪽의 전체 미리보기 / 전체 HWPX는 모든 챕터를 목록 순서대로 합친다. 전체 미리보기에서 전체 페이지 보기도 사용할 수 있다. 표지는 프로젝트 설정에 따라 한 번 포함된다.

7. 검토 담당자·비고 — 담당자 칸의 담당자 입력/수정, 비고 칸의 검토 내용 편집을 누르면 팝업이 열린다. 담당자 이름과 긴 검토 의견을 줄바꿈해서 작성하고 저장한다. 목록에는 담당자와 비고 요약이 표시된다. 같은 챕터를 다시 동기화해도 검토 정보는 유지되며, 미리보기·HWPX 본문에는 포함되지 않는다. 담당자 이름을 적는 것만으로 다른 계정에 프로젝트 접근 권한이 부여되지는 않는다.

8. 처음부터 다시 가져오기 — 챕터 표 머리글 오른쪽의 전체 삭제로 현재 챕터를 모두 비운 뒤, 원하는 분할 기준을 저장하고 전체 동기화하거나 원본 파일을 다시 업로드한다. 삭제 확인창에 개수가 표시된다. 챕터와 담당자·비고는 함께 삭제되고, 프로젝트 설정과 Google Docs 원본은 유지된다.

3. 원고(md) 작성 규칙

이 절만 지키면 된다. AI 에게 시킬 때는 4장의 프롬프트를 그대로 복사해서 쓰면 된다.

3.1 제목 — 가장 중요

# 의 개수가 한글 보고서 서식에 그대로 대응한다.

• ###### 이하는 전부 ##### 와 같게 처리된다. 5단계까지만 쓴다.
• # 제목에는 반드시 장 번호를 붙인다 (Ⅱ., II., 2., 제2장 다 인식). 이 번호가 표·그림 번호(<표 Ⅱ-1>)의 앞자리로 쓰인다. 장 번호가 없으면 자동 재번호가 꺼지고 원고에 쓴 캡션 글자가 그대로 나간다.

3.2 표

Google Docs에서는 표 바로 위의 별도 문단에 <표> 조사 대상을 적고, 그 아래에 표를 넣는다. 장 제목은 제목 1 스타일로 III. 연구 결과처럼 작성한다. Markdown에서는 다음과 같다.

# III. 연구 결과

<표> 조사 대상

| 구분 | 수 |
|---|---|
| 사업장 | 10 |

• 변환하면 <표 III-1> 조사 대상이 된다. 같은 장에서는 1, 2, 3으로 이어지고, 다음 장에서는 다시 1부터 시작한다.
• <표 III-99>처럼 기존 번호가 있어도 등장 순서대로 다시 매긴다. 〈표〉, [표]도 인식한다.
• 캡션과 표 사이에 다른 본문을 넣지 않는다. 빈 줄은 있어도 된다.
• HWPX에서는 표 위의 실제 개체 캡션에 숫자 자동번호를 넣는다. 캡션이 없는 표나 제목용 틀은 번호에 포함하지 않는다.
• Markdown 표에는 머리행 구분선(|---|)이 필요하다. 셀 병합은 지원하지 않는다.

3.3 그림

Google Docs에서는 그림을 넣고 바로 아래의 별도 문단에 [그림] 연구 절차를 적는다. 캡션 문단은 일반 본문 스타일로 두고, 그림과 캡션 사이에 다른 본문을 넣지 않는다.

III. 연구 결과  ← 제목 1 스타일

(그림 삽입)
[그림] 연구 절차

• 변환하면 [그림 III-1] 연구 절차가 된다. 표와 그림은 각각 별도로 번호를 매긴다.
• HWPX에서는 그림 아래의 실제 개체 캡션에 숫자 자동번호를 넣는다. 기존 원고의 그림 바로 위 캡션도 가져와 아래로 배치한다.
• 기존 <그림 III-1> 표기도 인식한다. 그림 없이 캡션 문단만 있으면 텍스트 제목으로 유지되며 개체 자동번호로 연결되지 않는다.
• Google Docs의 표시 자체는 [그림], <표>로 유지된다. 장 번호와 순번은 사이트 미리보기와 HWPX에 반영된다.
• 같은 장을 H2/H3로 나누어 가져온 경우에도 번호가 이어진다. HWPX의 숫자 부분은 자동번호이며, 앞의 장 표시(III-)는 원고의 장 제목을 기준으로 내보낼 때 정해진다.
• 그림 크기는 Docs의 설정을 반영하고 본문 폭을 넘으면 축소한다. 본문 흐름 안의 그림과 글 주위로 배치한 그림을 모두 가져온다.
• MD 업로드는 원고와 그림 파일을 묶은 ZIP을 사용한다.

3.4 각주

산업재해율은 2023년 기준 0.65%이다.[^1]

[^1]: 고용노동부, 「2023 산업재해 현황분석」, 2024.

• 정의([^1]: …)는 문서 맨 끝에 몰아 둬도 된다. 챕터를 쪼갤 때 필요한 각주 정의를 각 조각에 자동으로 따라 붙인다.
• Google Docs 로 작업할 때는 Docs 의 각주 기능(삽입 → 각주)을 쓰면 그대로 변환된다.

3.5 참고문헌

제목에 “참고문헌”(또는 References)이 들어가면, 그 뒤의 모든 문단이 참고문헌 스타일(내어쓰기)로 바뀐다. 그러므로 참고문헌 절은 문서 맨 끝에 둔다.

## 참고문헌

고용노동부, 「2023 산업재해 현황분석」, 2024.
안전보건공단, 「중대재해 사례집」, 2023.

3.6 목록·강조

• Google Docs에서 직접 입력한 - 항목은 하이픈 그대로 유지되고, 글머리표 기능으로 만든 항목은 동그라미 글머리표로 변환된다.
• Markdown의 - 항목은 글머리표 문법이다. 문자 하이픈으로 쓰려면 \- 항목처럼 이스케이프한다.
• 1. 항목 → 1) 항목 형태의 본문 문단으로 풀린다.
• **굵게**, *기울임*, 윗첨자·아랫첨자는 미리보기와 HWPX 모두에 유지된다. 본문·제목·표 셀·캡션·각주 안에서도 적용된다.
• Google Docs에서는 원래의 굵게/기울임/윗첨자/아랫첨자 서식을 적용하면 된다. 기존에 가져온 문서는 페이지 보기의 재동기화로 원본 서식을 다시 가져온다.
• Markdown에서는 m<sup>2</sup>, CO<sub>2</sub>처럼 쓴다. **<sup>강조 첨자</sup>**처럼 서식을 함께 적용할 수도 있다.
• 중첩 목록의 들여쓰기 단계는 표현되지 않는다. 깊은 중첩은 피한다.

4. AI 에게 줄 프롬프트 (복사해서 사용)

아래 규칙에 맞춰 마크다운(.md) 원고를 작성해 줘. 설명이나 인사말 없이 마크다운 본문만 출력해.

제목 체계

• # = 장. 반드시 장 번호로 시작한다. 예: # Ⅱ. 연구 내용 및 방법
• ## = 절 (## 1. 연구 대상), ### = ### 1) …, #### = #### (1) …, ##### = ##### 가) …
• ###### 이하는 쓰지 않는다.

표

• GFM 표만 쓰고 머리행 구분선(|---|)을 반드시 넣는다. 셀 병합은 쓰지 않는다.
• 표 바로 윗줄(빈 줄 하나 사이)에 <표> 표 제목 형식의 캡션 문단을 둔다.

그림

• 마크다운에 이미지를 넣지 말고 [그림] 그림 제목 캡션 문단만 쓴다. (그림 자체는 사람이 Google 문서에서 해당 캡션 바로 위에 붙여넣는다.)

각주

• 본문에 [^1], 문서 끝에 [^1]: 출처 형식으로 단다.

참고문헌

• 문서 맨 끝에 ## 참고문헌 절을 두고, 항목마다 한 문단씩 쓴다.

금지

• 코드 블록(```), HTML 태그, 이미지 삽입, 수평선(---), 중첩 목록.

주제: (여기에 쓸 내용)

5. 되는 것 / 안 되는 것

6. 잘 안 될 때

7. 담당자용 메모

• 소스: sites/hwpx/ · 포트 8480 · DB 는 자체 sqlite3
• 변환 파이프라인: chapters/services/gdoc_json.py(Docs JSON→md) → chapters/converter/mdparse.py(md→IR) → chapters/converter/hwpx.py(IR→hwpx)
• 그림: Docs 의 그림은 ![alt](asset:<sha256>) 로 md 에 남고, 원본은 media/assets/ 아래에 내용 해시로 저장된다(Asset 모델). hwpx 포장 시 BinData/imageN.* 로 실린다. hp:pic 는 좌표계가 둘이다 — imgDim·imgClip·imgRect·orgSz 는 원본 크기, curSz·sz 는 표시 크기, scaMatrix 는 그 비율. imgClip 에 표시 크기를 넣으면 원본의 왼쪽 위만 오려낸 그림이 된다 (2026-08-23 에 그 버그가 있었다).
• 표는 3선표(위·아래 굵은 선, 안쪽 얇은 선, 좌우 바깥선 없음)로 나간다. 새 borderFill 을 header.xml 뒤에 덧붙이면 한글이 무시하고 테두리를 안 그린다. 그래서 개수는 60개 그대로 두고, header.xml 안에서 참조되지 않는 id(1·2·3·6 외)의 정의만 제자리에서 바꿔 쓴다 — chapters/converter/hwpx.py 의 BF_IDS 참조.
• 한글 스타일 정의는 assets/hwpx_template/Contents/header.xml 에 있고, 블록→스타일 매핑표는 chapters/converter/hwpx.py 상단 HEADING_STYLE 등에 있다.
• 서비스 계정 키: local_assets/sec/gen-lang-client-*.json (settings.py GOOGLE_SA_JSON)
• 재시작 방법은 kosha-server/CLAUDE.md 참조 (HUP 금지, 마스터 kill).