### Clone Repository and Setup Project
Source: https://github.com/roboco-io/hwp2md/blob/main/README.md
Clone the repository, navigate into the directory, download dependencies, and install Git hooks. This is the initial setup for development.
```bash
# 저장소 클론
git clone https://github.com/roboco-io/hwp2md.git
cd hwp2md
# 의존성 다운로드
go mod download
# Git hooks 설치 (필수)
make hooks
# 빌드
make build
```
--------------------------------
### Development Environment Setup Commands
Source: https://github.com/roboco-io/hwp2md/blob/main/docs/tech-stack.md
These commands guide you through setting up the development environment. Clone the repository, download dependencies, and then use 'make' commands for building and testing.
```bash
# 저장소 클론
git clone https://github.com/roboco-io/hwp2md.git
cd hwp2md
# 의존성 다운로드
go mod download
# 빌드
make build
# 테스트
make test
# 린트 (golangci-lint 필요)
make lint
```
--------------------------------
### Install hwp2md via Go
Source: https://github.com/roboco-io/hwp2md/blob/main/README.md
Install the latest version of the hwp2md CLI tool using the Go toolchain.
```bash
go install github.com/roboco-io/hwp2md/cmd/hwp2md@latest
```
--------------------------------
### Header XML Example (header.xml)
Source: https://github.com/roboco-io/hwp2md/blob/main/docs/hwpx-schema.md
Shows the structure of the header.xml file, which contains global document settings such as title, styles, and numbering configurations.
```xml
문서 제목
```
--------------------------------
### Content Manifest (content.hpf) Example
Source: https://github.com/roboco-io/hwp2md/blob/main/docs/hwpx-schema.md
An example of the content.hpf file, which acts as the package manifest and declares all part files within the HWPX archive. Parsers use this to identify section and binary files.
```xml
```
--------------------------------
### Section XML Example (sectionN.xml)
Source: https://github.com/roboco-io/hwp2md/blob/main/docs/hwpx-schema.md
An example of a sectionN.xml file, containing the actual body content of the document, including paragraphs, tables, and other elements.
```xml
일반 텍스트입니다.
```
--------------------------------
### Install Git Hooks
Source: https://github.com/roboco-io/hwp2md/blob/main/README.md
Install the Git hooks that automate code quality checks before commits and pushes. This ensures code consistency and adherence to project standards.
```bash
# hooks 설치
make hooks
```
--------------------------------
### Image Element Example
Source: https://github.com/roboco-io/hwp2md/blob/main/docs/hwpx-schema.md
Shows the structure for embedding images (`hd:pic`) in HWPX, referencing binary data via `binItemIDRef` and specifying dimensions and alt text.
```xml
```
--------------------------------
### HWP 5.x OLE 파일 파싱 구현
Source: https://github.com/roboco-io/hwp2md/blob/main/docs/tech-stack.md
mscfb 패키지를 사용하여 HWP 5.x 형식의 OLE/CFBF 구조를 파싱합니다.
```go
import "github.com/richardlehane/mscfb"
func parseHWP5(path string) (*Document, error) {
file, err := os.Open(path)
if err != nil {
return nil, err
}
defer file.Close()
doc, err := mscfb.New(file)
if err != nil {
return nil, err
}
for entry, err := doc.Next(); err == nil; entry, err = doc.Next() {
// FileHeader, DocInfo, BodyText/Section0 등 처리
fmt.Println(entry.Name)
}
return &Document{}, nil
}
```
--------------------------------
### OpenAI Provider Implementation in Go
Source: https://github.com/roboco-io/hwp2md/blob/main/docs/tech-stack.md
Implements the OpenAI LLM provider, including initialization, validation, and formatting capabilities. Requires an API key and model name for configuration.
```go
package openai
import (
"context"
"github.com/sashabaranov/go-openai"
"github.com/roboco-io/hwp2md/internal/llm"
)
type OpenAIProvider struct {
client *openai.Client
model string
}
func New(apiKey, model string) *OpenAIProvider {
return &OpenAIProvider{
client: openai.NewClient(apiKey),
model: model,
}
}
func (p *OpenAIProvider) Name() string {
return "openai"
}
func (p *OpenAIProvider) Validate() error {
if p.client == nil {
return fmt.Errorf("OpenAI client not initialized")
}
return nil
}
func (p *OpenAIProvider) Format(ctx context.Context, ir *llm.IntermediateRepresentation, opts llm.FormatOptions) (*llm.FormatResult, error) {
prompt := buildPrompt(ir, opts)
resp, err := p.client.CreateChatCompletion(ctx, openai.ChatCompletionRequest{
Model: p.model,
Messages: []openai.ChatCompletionMessage{
{Role: "system", Content: systemPrompt},
{Role: "user", Content: prompt},
},
MaxTokens: opts.MaxTokens,
Temperature: float32(opts.Temperature),
})
if err != nil {
return nil, err
}
return &llm.FormatResult{
Markdown: resp.Choices[0].Message.Content,
TokensUsed: resp.Usage.TotalTokens,
Model: p.model,
}, nil
}
```
--------------------------------
### Perform Basic Document Conversion
Source: https://github.com/roboco-io/hwp2md/blob/main/README.md
Convert HWP or HWPX files to Markdown using the default native parser.
```bash
# HWPX 파일을 Markdown으로 변환
hwp2md document.hwpx -o output.md
# HWP 5.x 파일을 Markdown으로 변환
hwp2md document.hwp -o output.md
# 표준 출력으로 변환
hwp2md document.hwpx
```
--------------------------------
### Paragraph Element Example
Source: https://github.com/roboco-io/hwp2md/blob/main/docs/hwpx-schema.md
Demonstrates the structure of a paragraph element (`hp:p`) within HWPX, including text runs, tabs, and line breaks. Note the use of `styleIDRef` for styling.
```xml
텍스트 내용
```
--------------------------------
### Table Element Example
Source: https://github.com/roboco-io/hwp2md/blob/main/docs/hwpx-schema.md
Illustrates the structure of a table element (`ht:tbl`) in HWPX, showing rows (`ht:tr`) and cells (`ht:tc`). Cells contain paragraph elements for their content.
```xml
셀 1
셀 2
```
--------------------------------
### Project Structure
Source: https://github.com/roboco-io/hwp2md/blob/main/docs/tech-stack.md
The project is organized into several directories including cmd, internal, pkg, testdata, and docs. Each directory serves a specific purpose in the project's architecture.
```tree
hwp2md/
├── cmd/
│ └── hwp2md/
│ └── main.go # 진입점
├── internal/
│ ├── cli/
│ │ ├── root.go # cobra 루트 커맨드
│ │ ├── convert.go # convert 서브커맨드
│ │ ├── extract.go # extract 서브커맨드
│ │ ├── providers.go # providers 서브커맨드
│ │ └── config.go # config 서브커맨드
│ ├── parser/
│ │ ├── parser.go # 파서 인터페이스
│ │ ├── hwpx.go # HWPX 파서
│ │ ├── hwp5.go # HWP 5.x 파서
│ │ └── detector.go # 포맷 감지
│ ├── ir/
│ │ ├── ir.go # Intermediate Representation 정의
│ │ ├── paragraph.go # 문단 IR
│ │ ├── table.go # 테이블 IR
│ │ └── image.go # 이미지 IR
│ ├── llm/
│ │ ├── provider.go # LLM Provider 인터페이스
│ │ ├── registry.go # Provider Registry
│ │ ├── openai/
│ │ │ └── openai.go # OpenAI Provider
│ │ ├── anthropic/
│ │ │ └── anthropic.go # Anthropic Provider
│ │ ├── gemini/
│ │ │ └── gemini.go # Google Gemini Provider
│ │ └── ollama/
│ │ └── ollama.go # Ollama Provider (로컬)
│ ├── config/
│ │ ├── config.go # 설정 관리
│ │ └── loader.go # 설정 파일 로더
│ └── renderer/
│ ├── renderer.go # 렌더러 인터페이스
│ ├── markdown.go # Markdown 렌더러
│ └── text.go # Plain Text 렌더러
├── pkg/
│ └── hwp2md/
│ └── convert.go # 공개 API
├── testdata/
│ ├── sample.hwpx
│ ├── sample.hwp
│ └── expected.md # 테스트 기대 결과
├── docs/
│ ├── hwp-format-research.md
│ ├── existing-solutions-research.md
│ ├── PRD.md
│ └── tech-stack.md
├── go.mod
├── go.sum
├── Makefile
├── README.md
├── LICENSE
└── .github/
└── workflows/
├── test.yml
└── release.yml
```
--------------------------------
### Cobra CLI 프레임워크 설정
Source: https://github.com/roboco-io/hwp2md/blob/main/docs/tech-stack.md
Cobra를 사용하여 CLI 명령 구조와 플래그를 정의합니다.
```go
package cmd
import (
"github.com/spf13/cobra"
)
var rootCmd = &cobra.Command{
Use: "hwp2md",
Short: "HWP/HWPX 문서를 Markdown으로 변환",
Long: `HWP(한글 워드프로세서) 문서를 Markdown으로 변환하는 CLI 도구입니다.`,
}
var convertCmd = &cobra.Command{
Use: "convert [input]",
Short: "HWP/HWPX 파일을 Markdown으로 변환",
Args: cobra.ExactArgs(1),
RunE: func(cmd *cobra.Command, args []string) error {
input := args[0]
output, _ := cmd.Flags().GetString("output")
return convert(input, output)
},
}
func init() {
convertCmd.Flags().StringP("output", "o", "", "출력 파일")
convertCmd.Flags().String("extract-images", "", "이미지 추출 디렉토리")
rootCmd.AddCommand(convertCmd)
}
```
--------------------------------
### 변환기 실행 명령어
Source: https://github.com/roboco-io/hwp2md/blob/main/docs/hwpx-markdown-differences.md
hwp2md 변환기를 사용하여 문서를 변환하는 방법입니다. --llm 옵션을 통해 가독성을 개선할 수 있습니다.
```bash
# Stage 1만 (파서)
hwp2md convert document.hwpx
# Stage 2 포함 (LLM 포맷팅)
hwp2md convert document.hwpx --llm
```
--------------------------------
### Makefile for Build, Test, Lint, Clean, and Release
Source: https://github.com/roboco-io/hwp2md/blob/main/docs/tech-stack.md
The Makefile defines common development tasks. Use 'make build' to compile, 'make test' to run tests, 'make lint' for code linting, 'make clean' to remove build artifacts, and 'make release' to prepare release binaries.
```makefile
.PHONY: build test lint clean release
VERSION ?= $(shell git describe --tags --always --dirty)
LDFLAGS := -ldflags="-s -w -X main.version=$(VERSION)"
build:
go build $(LDFLAGS) -o bin/hwp2md ./cmd/hwp2md
test:
go test -v -race -cover ./...
lint:
golangci-lint run
clean:
rm -rf bin/ dist/
release:
GOOS=windows GOARCH=amd64 go build $(LDFLAGS) -o dist/hwp2md-windows-x64.exe ./cmd/hwp2md
GOOS=darwin GOARCH=amd64 go build $(LDFLAGS) -o dist/hwp2md-macos-x64 ./cmd/hwp2md
GOOS=darwin GOARCH=arm64 go build $(LDFLAGS) -o dist/hwp2md-macos-arm64 ./cmd/hwp2md
GOOS=linux GOARCH=amd64 go build $(LDFLAGS) -o dist/hwp2md-linux-x64 ./cmd/hwp2md
```
--------------------------------
### Go API: Convert HWPX with Options
Source: https://github.com/roboco-io/hwp2md/blob/main/docs/PRD.md
Use the Go API to convert a .hwpx file. Options can be set to extract images or enable LLM formatting.
```go
import "github.com/roboco-io/hwp2md/pkg/hwp2md"
// Stage 1만: 텍스트 추출 + 기본 Markdown 변환
result, err := hwp2md.Convert("document.hwpx", hwp2md.Options{
ExtractImages: true,
ImageDir: "./images",
})
```
```go
// Stage 1 + Stage 2: LLM 포맷팅 활성화
result, err := hwp2md.Convert("document.hwpx", hwp2md.Options{
UseLLM: true, // LLM 포맷팅 활성화
Provider: "anthropic",
Model: "claude-sonnet-4-20250514",
ExtractImages: true,
ImageDir: "./images",
})
```
--------------------------------
### HWP 파일 구조 시각화
Source: https://github.com/roboco-io/hwp2md/blob/main/docs/hwp5-research.md
HWP 5.x 파일의 계층적 OLE2 Compound File 구조를 나타냅니다.
```text
HWP 파일
├── FileHeader # 파일 인식 정보 (고정 256바이트)
├── DocInfo # 문서 정보 (압축/암호화 가능)
├── BodyText/ # 본문 저장소
│ ├── Section0 # 첫 번째 섹션
│ ├── Section1 # 두 번째 섹션
│ └── ...
├── BinData/ # 바이너리 데이터 저장소
│ ├── BIN0001.jpg # 이미지 등
│ └── ...
├── PrvText # 미리보기 텍스트
├── PrvImage # 미리보기 이미지
└── Scripts/ # 스크립트 저장소 (선택)
```
--------------------------------
### Run All Tests
Source: https://github.com/roboco-io/hwp2md/blob/main/README.md
Execute all unit and end-to-end tests for the project. This command ensures the entire application functions as expected.
```bash
# 전체 테스트
make test
```
--------------------------------
### Go API Options Struct
Source: https://github.com/roboco-io/hwp2md/blob/main/docs/PRD.md
Defines the configuration options for the hwp2md conversion process, including LLM settings and image extraction.
```go
type Options struct {
UseLLM bool // LLM 포맷팅 활성화 (기본값: false)
Provider string // LLM 프로바이더 (openai, anthropic, gemini, ollama)
Model string // LLM 모델
ExtractImages bool // 이미지 추출 여부
ImageDir string // 이미지 저장 디렉토리
}
```
--------------------------------
### Enable LLM Formatting
Source: https://github.com/roboco-io/hwp2md/blob/main/README.md
Apply LLM-based formatting to the generated Markdown to improve readability, supporting various providers.
```bash
# Anthropic Claude 사용 (기본)
export ANTHROPIC_API_KEY="your-api-key"
hwp2md convert document.hwpx --llm
# OpenAI GPT 사용
export OPENAI_API_KEY="your-api-key"
hwp2md convert document.hwpx --llm --provider openai
# Google Gemini 사용
export GOOGLE_API_KEY="your-api-key"
hwp2md convert document.hwpx --llm --provider gemini
# Upstage Solar 사용
export UPSTAGE_API_KEY="your-api-key"
hwp2md convert document.hwpx --llm --provider upstage
# Ollama 사용 (로컬)
hwp2md convert document.hwpx --llm --provider ollama --model llama3.2
```
--------------------------------
### 셀 병합 변환 예시
Source: https://github.com/roboco-io/hwp2md/blob/main/docs/hwpx-markdown-differences.md
HWPX의 셀 병합 구조를 Markdown 테이블로 변환하는 예시입니다.
```markdown
| 항목 | 값1 |
| | 값2 |
```
```markdown
| 항목 | 값1 |
| 〃 | 값2 |
```