HWPX 변환기 사용법

주소: https://kosha.ai.kr/hwpx/

원고(마크다운 또는 Google Docs)를 한글 보고서 서식이 입혀진 .hwpx 파일로 바꿔 준다. 장(章) 단위로 파일이 하나씩 나오므로, 받아서 한글에서 열고 이어 붙이면 된다.

1. 전체 흐름

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

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

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

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

둘 중 아무거나.

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

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

2. 사이트 사용 순서

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

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

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

   (화면에도 같은 주소가 적혀 있다. 그 화면의 값이 항상 맞다.)

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

   • 제목 1 : 장별 문서 여러 개를 폴더에 넣는 보통의 경우
   • 제목 2 / 제목 3 : 긴 문서 하나를 절 단위로 쪼갤 때. 이때 잘린 조각의 제목 수준이 자동으로 올라간다 (선택한 수준 → 장).

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

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

5. 미리보기 — 챕터 제목을 누르면 변환 결과가 보인다. 페이지 보기는 A4 조판·각주 위치까지 실제와 비슷하게 보여 준다. 위쪽에 ⚠ 경고가 뜨면 무엇이 빠졌는지 알려 주는 것이다 (5장 참조).

6. 내려받기 — [HWPX ↓]. 파일명은 001_Ⅱ. 연구 내용.hwpx 처럼 순서번호가 붙는다.

3. 원고(md) 작성 규칙

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

3.1 제목 — 가장 중요

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

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

3.2 표

GFM 표 문법을 쓰고, 머리행(구분선 |---|)을 반드시 넣는다.

<표 Ⅱ-1> 조사 대상 사업장 분포

| 구분 | 사업장 수 | 비율(%) |
|---|---|---|
| 제조업 | 120 | 48.0 |
| 건설업 | 80 | 32.0 |

• 표 바로 위 문단이 <표 로 시작하면 그 문단이 표 제목이 된다 (가운데 정렬). 〈표, [표 도 인식한다. 표에서 한 줄이라도 떨어지면 그냥 본문이 되니 주의.
• 번호는 사이트가 다시 매긴다. <표 Ⅱ-1> 이라고 적어도 등장 순서대로 <표 Ⅱ-1>, <표 Ⅱ-2> … 로 자동 교정된다. 같은 장이 여러 파일로 나뉘어도 번호가 이어진다. 그러니 번호를 정확히 맞추려고 애쓸 필요 없다. <표> 제목 만 써도 된다.
• 셀 병합은 표현할 수 없다. 병합 없는 격자표로 만든다.

3.3 그림

Google Docs 로 작업하면 그림이 그대로 hwpx 에 들어간다. 문서 본문에 그림을 붙여넣기만 하면, 동기화할 때 서버가 그 이미지를 받아서 hwpx 안에 심는다. 파일명을 맞추거나 따로 업로드할 필요가 없다.

• 그림 아래(또는 위)에 캡션 문단을 둔다:

  <그림 Ⅱ-1> 연도별 재해율 추이
  

• 그림 제목은 위치와 상관없이 인식되고, 번호도 표와 별개로 자동으로 매겨진다.

• 크기는 Docs 에서 보이는 크기를 그대로 쓴다. 본문 폭보다 크면 폭에 맞춰 줄인다. Docs 에서 그림 크기를 조절해 두면 그 비율대로 나온다.

• 본문 흐름 안에 넣은 그림과 글 주위로 배치한 그림 둘 다 가져온다.

• .md 파일만 업로드하는 경로에는 그림이 없다 (파일 하나에 이미지가 안 담긴다). 그림이 있는 원고는 Google Docs 경로를 쓴다.

3.4 각주

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

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

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

3.5 참고문헌

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

## 참고문헌

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

3.6 목록·강조

• - 항목 → 불릿(∙) 스타일.
• 1. 항목 → 1) 항목 형태의 본문 문단으로 풀린다.
• **굵게**, *기울임* 은 유지된다.
• 중첩 목록의 들여쓰기 단계는 표현되지 않는다. 깊은 중첩은 피한다.

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

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

제목 체계

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

표

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

그림

• 마크다운에 이미지를 넣지 말고 <그림 Ⅱ-1> 그림 제목 캡션 문단만 쓴다. (그림 자체는 사람이 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).