test/templates/hwp_guide.md

A4 HTML 문서 레이아웃 가이드

이 가이드는 글벗 doc_template_analyzer가 HWPX에서 추출한 구조를 A4 규격 HTML template.html로 변환할 때 참조하는 레이아웃 규격입니다.

★ 이 파일의 값은 코드에 하드코딩하지 않습니다. ★ doc_template_analyzer._build_css(), _build_full_html() 등에서 이 파일을 읽어 적용합니다. ★ 색상, 폰트 등 스타일은 HWPX에서 추출한 값을 우선 사용하고, 없으면 이 가이드의 기본값을 사용합니다.

---

1. 페이지 규격 (Page Dimensions)

page:
  width: 210mm          # A4 가로
  height: 297mm         # A4 세로
  background: white
  boxSizing: border-box

margins:
  top: 20mm             # 상단 여백 (머릿말 + 본문 시작)
  bottom: 20mm          # 하단 여백 (꼬릿말 + 본문 끝)
  left: 20mm            # 좌측 여백
  right: 20mm           # 우측 여백

# 본문 가용 높이 = 297mm - 20mm(상) - 20mm(하) = 257mm ≈ 970px
bodyMaxHeight: 970px

2. HTML 골격 구조 (Page Structure)

각 페이지는 .sheet 클래스로 감싸며, 내부에 header/body/footer를 absolute로 배치합니다.

<!-- 페이지 단위 -->
<div class="sheet">
    <!-- 머릿말: 상단 여백(20mm) 안, 위에서 10mm 지점 -->
    <div class="page-header">
        <!-- HWPX 머릿말 테이블 내용 -->
    </div>
    
    <!-- 본문: 상하좌우 20mm 안쪽 -->
    <div class="body-content">
        <!-- 섹션 제목, 표, 개조식 등 -->
    </div>
    
    <!-- 꼬릿말: 하단 여백(20mm) 안, 아래에서 10mm 지점 -->
    <div class="page-footer">
        <!-- HWPX 꼬릿말 테이블 내용 -->
    </div>
</div>

3. 핵심 CSS 레이아웃 (Layout CSS)

3.1 용지 (.sheet)

.sheet {
    width: 210mm;
    height: 297mm;
    background: white;
    margin: 20px auto;          /* 화면 미리보기용 */
    position: relative;
    overflow: hidden;
    box-sizing: border-box;
    box-shadow: 0 0 15px rgba(0,0,0,0.1);
}

3.2 인쇄 대응

@media print {
    .sheet { margin: 0; break-after: page; box-shadow: none; }
    body { background: white; }
}

3.3 머릿말 (.page-header)

.page-header {
    position: absolute;
    top: 10mm;                  /* 상단 여백(20mm)의 중간 */
    left: 20mm;
    right: 20mm;
    font-size: 9pt;
    padding-bottom: 5px;
}

• 머릿말이 테이블 형태인 경우: <table> 사용, 테두리 없음
• HWPX에서 추출한 열 수와 셀 내용을 placeholder로 배치
• 다중행 셀은 <br>로 줄바꿈

3.4 꼬릿말 (.page-footer)

.page-footer {
    position: absolute;
    bottom: 10mm;               /* 하단 여백(20mm)의 중간 */
    left: 20mm;
    right: 20mm;
    font-size: 9pt;
    color: #555;
    border-top: 1px solid #eee;
    padding-top: 5px;
}

• 꼬릿말이 테이블 형태인 경우: <table> 사용, 테두리 없음
• 2열 이상일 때 display: flex; justify-content: space-between 패턴도 가능
• 페이지 번호는 별도 <span class="pg-num"> 으로

3.5 본문 영역 (.body-content)

.body-content {
    position: absolute;
    top: 20mm;
    left: 20mm;
    right: 20mm;
    bottom: 20mm;               /* 또는 auto + JS 제어 */
}

4. 타이포그래피 기본값 (Typography Defaults)

HWPX에서 폰트/크기를 추출했으면 그 값을 사용합니다. 추출 실패 시 아래 기본값을 적용합니다.

typography:
  fontFamily: "'Noto Sans KR', sans-serif"
  fontImport: "https://fonts.googleapis.com/css2?family=Noto+Sans+KR:wght@300;400;500;700;900&display=swap"
  
  body:
    fontSize: 12pt
    lineHeight: 1.6
    textAlign: justify
    wordBreak: keep-all        # 한글 단어 중간 끊김 방지
  
  heading:
    h1: { fontSize: 20pt, fontWeight: 900 }
    h2: { fontSize: 18pt, fontWeight: 700 }
    h3: { fontSize: 14pt, fontWeight: 700 }
  
  headerFooter:
    fontSize: 9pt
  
  table:
    fontSize: 9.5pt
    thFontSize: 9pt

5. 표 스타일 기본값 (Table Defaults)

table:
  width: "100%"
  borderCollapse: collapse
  tableLayout: fixed            # colgroup 비율 적용 시 fixed 필수
  borderTop: "2px solid"        # 상단 굵은 선 (색상은 HWPX 추출)
  
  th:
    fontWeight: 900
    textAlign: center
    verticalAlign: middle
    whiteSpace: nowrap           # 헤더 셀은 한 줄 유지
    wordBreak: keep-all
    padding: "6px 5px"
  
  td:
    textAlign: center
    verticalAlign: middle
    wordBreak: keep-all
    wordWrap: break-word
    padding: "6px 5px"
    border: "1px solid #ddd"

6. 머릿말/꼬릿말 테이블 (Header/Footer Table)

머릿말/꼬릿말이 HWPX에서 테이블로 구성된 경우:

headerFooterTable:
  border: none                  # 테두리 없음
  width: "100%"
  fontSize: 9pt
  
  # 열 역할 패턴 (HWPX에서 추출)
  # 보통 3열: [소속정보 | 빈칸/로고 | 작성자/날짜]
  # 또는 2열: [제목 | 페이지번호]
  
  cellStyle:
    padding: "2px 5px"
    verticalAlign: middle
    border: none

7. 개조식 (Bullet Style)

bulletList:
  marker: "·"                   # 한국 문서 기본 불릿
  className: "bullet-list"
  
  css: |
    .bullet-list {
        list-style: none;
        padding-left: 15px;
        margin: 5px 0;
    }
    .bullet-list li::before {
        content: "· ";
        font-weight: bold;
    }
    .bullet-list li {
        margin-bottom: 3px;
        line-height: 1.5;
    }

8. 색상 (Color Scheme)

HWPX에서 추출한 색상을 CSS 변수로 주입합니다. 추출 실패 시 아래 기본값을 사용합니다.

colors:
  # Navy 계열 (기본)
  primary: "#1a365d"
  accent: "#2c5282"
  lightBg: "#EBF4FF"
  
  # 문서별 오버라이드 (HWPX 추출값)
  # doc_template_analyzer가 HWPX의 글자색/배경색을 분석하여
  # 이 값을 덮어씁니다.
  
  css: |
    :root {
        --primary: #1a365d;
        --accent: #2c5282;
        --light-bg: #EBF4FF;
        --bg: #f5f5f5;
    }

9. 페이지 분할 규칙 (Page Break Rules)

pageBreak:
  # H1(대제목)에서만 강제 페이지 분할
  h1Break: true
  
  # H2/H3이 페이지 하단에 홀로 남지 않도록
  orphanControl: true
  orphanMinSpace: 90px          # 이 공간 미만이면 다음 페이지로
  
  # 표/그림은 분할하지 않음
  atomicBlocks:
    - table
    - figure
    - ".highlight-box"
  
  # break-inside: avoid 적용 대상
  avoidBreakInside:
    - table
    - figure
    - ".atomic-block"

10. 배경 (Preview Background)

preview:
  bodyBackground: "#525659"     # 회색 배경 위에 흰색 용지
  # 인쇄 시 배경 제거 (@media print)

---

★ 사용 방법 (How doc_template_analyzer uses this guide)

1. doc_template_analyzer._build_full_html() 호출 시:

   • 이 가이드 파일을 읽음
   • HWPX에서 추출한 스타일(색상, 폰트, 크기)이 있으면 오버라이드
   • 없으면 가이드 기본값 사용

2. CSS 생성 순서:

   가이드 기본값 → HWPX 추출 스타일 오버라이드 → CSS 변수로 통합
   

3. HTML 구조:

   가이드의 골격(.sheet > .page-header + .body-content + .page-footer)
   + HWPX에서 추출한 placeholder 배치
   = template.html
   

4. 색상 결정:

   HWPX headerTextColor → --primary
   HWPX headerBgColor → --light-bg  
   없으면 → 가이드 기본값(Navy 계열)