Markdown Adapter for Paragraph-Style Injection
Mapsi 는 마크다운 문서를 한/글 hwpx 로 변환하는 도구이다. "맵시" 는 "모양새, 차림새" 를 뜻하는 한국어이며, 본 프로젝트는 마크다운의 구조를 hwpx 의 스타일로 맵시 있게 옮기는 도구이다.
연구자와 개발자가 보편적으로 사용하는 마크다운 형식을 학술지와 공공기관 및 정부 문서 작성에서 필수적으로 요구되는 hwpx 형식으로 변환하는 것이 핵심 목적이다. 두 형식 사이의 차이를 줄여, 한번 작성한 문서를 두 환경에서 모두 활용할 수 있도록 한다.
변환의 핵심 원리는 마크다운의 포맷 요소와 hwpx 의 스타일 이름을 1:1 로 매칭시키는 것이다. 마크다운의 제목은 개요 1-6 스타일로, 글머리 목록은 네모/동그라미/줄 스타일로, 번호 목록은 번호 1-3 스타일로 매핑된다. 인용은 인용 스타일, 코드 블록은 코드 스타일, 표는 표내용/표캡션 스타일, 그림은 그림/그림캡션 스타일에 대응된다.
본 변환기는 시각 속성(폰트, 색, 들여쓰기 등)을 스스로 결정하지 않는다. 변환기의 책임은 마크다운의 모든 구조 단위에 올바른 hwpx 스타일 이름을 부착하는 데까지이며, 시각 속성의 최종 조정은 사용자가 hwpx 스타일 편집창에서 수행한다. 사용자는 이 분담 덕분에 최초에 작성한 마크다운 파일을 부담없이 hwpx 파일로 변환할 수 있고, 한/글의 뛰어난 스타일 기능을 이용하여 hwpx 스타일 수정을 통해 문서 전체에 일관된 서식을 적용할 수 있다.
즉 Mapsi 는 마크다운으로 hwpx 의 최소한의 골격을 만들고, 보다 자세한 맞춤화(customization)는 hwpx 자체의 스타일 편집을 통해 구현하도록 하는 설계를 따른다.
Mapsi 는 마크다운의 다음 요소를 대응하는 hwpx 스타일로 매핑한다.
| 마크다운 요소 | hwpx 스타일 |
|---|---|
# - ###### 제목 |
개요 1 - 개요 6 |
- 또는 * 글머리 목록 (깊이 1-3) |
네모, 동그라미, 줄 |
1. 번호 목록 (깊이 1-3) |
번호 1, 번호 2, 번호 3 |
> 인용 블록 |
인용 |
| 코드 블록 | 코드 |
| GFM 파이프 표 | 표내용, 표캡션 |
| 이미지 참조 | 그림, 그림캡션 |
각주 [^N] |
각주 (자동 번호매김) |
| 참고문헌 섹션 | 참고문헌 |
| 인라인 서식 | 굵게, 기울임, 취소선, 코드, 하이퍼링크 |
수식 $...$ / $$...$$ |
hp:equation (v0.2) |
쪽번호, 용지, 여백, 기본 글꼴 같은 문서 전역 설정은 base 템플릿에서 상속된다.
| 날짜 | 버전 | 내용 |
|---|---|---|
| 2026-04-18 | 0.1 | 앱 프로젝트 기획안 작성 |
| 2026-04-21 | 0.2 | 앱 프로토타입 완성 |
목적에 따라 다음 중 하나를 선택한다. 추후 제공 예정.
추후 제공 예정.
| 예정일 | 내용 |
|---|---|
| 2026-05-24 | 수식 편집기 및 BibTeX 연동 완성 |
현재 v0.1 의 수식 처리는 [hnc 수식]...[/hnc 수식] 평문 마커를 본문에 박는 방식이다. v0.2 에서는 hp:equation XML 요소를 직접 생성하여, 한/글이 파일을 열 때 즉시 렌더링된 수식이 표시되도록 한다. 사용자의 수동 복사 붙여넣기가 불필요해진다.
학술 문서 작성 시 자주 사용되는 BibTeX 서지 파일을 마크다운 본문의 [@citekey] 참조와 연결하여, 참고문헌 섹션을 자동 생성하는 기능을 추가한다. Pandoc 의 citation 처리와 유사한 경험을 제공하되 결과는 한/글 참고문헌 스타일로 출력된다.
향후 다음 기능들을 단계적으로 추가할 계획이다.
사용자 정의 스타일 매핑 YAML 지원, 설명 목록(definition list) 지원, 표 셀 내부의 인라인 서식 지원, 각주와 수식과 인라인 서식의 동시 등장 처리, 역변환(hwpx → 마크다운) 등이다.
마크다운의 구조적 역할을 한/글 스타일 이름에 매핑한다. 시각 속성(폰트, 색, 들여쓰기)은 결정하지 않으며, 사용자가 한/글의 스타일 편집기에서 일괄 조정하면 된다.
정책과 사실을 분리한다. Mapsi 는 "어떤 마크다운 요소를 어떤 한/글 스타일 이름에 매핑할 것인가" 라는 정책만 관리하며, 한/글 스타일의 내부 구조는 한/글이 제공한 그대로 사용한다. 덕분에 한/글의 버전 변경이나 Mapsi 의 정책 변경이 서로 독립적으로 반영된다.
버그 제보와 개선 제안은 GitHub Issues 에 부탁 드린다. 코드 기여 전에는 docs/ 아래의 개발자 문서를 참조하기 바란다.
본 프로젝트는 MIT License 하에 배포된다. 자세한 내용은 LICENSE 파일을 참조하기 바란다. 기여자 명단은 CONTRIBUTORS.md 를 참조한다.
본 프로젝트의 설계 상세와 개발자 온보딩 자료는 다음 문서들에서 확인할 수 있다.
- 프로젝트 전체 계획
- 개발자 B 핸드오프 — 코어 엔진 담당
- 개발자 C 핸드오프 — 주변 인프라 담당
- API 인터페이스 계약 — 모듈 경계
- 골든 회귀 테스트 가이드
- 아키텍처 결정 기록 — ADR 모음