Markdown to DOCX 변환기

마크다운 파일을 Word(DOCX) 포맷으로 변환합니다. 라이브러리로도 사용 가능하며 CLI 도구로도 사용할 수 있습니다. TypeScript로 작성되어 완벽한 타입 안정성을 제공합니다.

주요 기능

- ✅ 마크다운 파싱: 제목(H1-H6), 목록, 인용문 자동 감지
- ✅ 인라인 포맷팅: bold, _italic_, code 완벽 지원
- ✅ 테이블: 마크다운 테이블 지원
- ✅ 링크: 텍스트 형식 지원
- ✅ 이미지 링크: !alt 형식 지원
- ✅ 체크박스: - [ ], - [x] 형식 지원
- ✅ HTML 마크업:
,

---

등 HTML 태그 자동 처리
- ✅ 통일된 폰트: 기본값 맑은 고딕, 명령줄/코드로 변경 가능
- ✅ 모듈화: 라이브러리로 재사용 가능
- ✅ TypeScript: 완벽한 타입 안정성

설치

$3

nodejs.org에서 다운로드 후 설치

$3

``bash
npm install -g markdown-to-docx
`

$3

`bash


저장소 클론

git clone https://github.com/your-username/markdown-to-docx.git
cd markdown-to-docx

의존성 설치 및 빌드

npm install
npm run build

전역 등록

npm link
`

사용 방법

$3

`bash


기본 사용 (input.md → output.docx)

markdown-to-docx

파일명 지정

markdown-to-docx --input "마크다운파일.md"

폰트 변경

markdown-to-docx --font "나눔고딕"

모든 옵션

markdown-to-docx --input "문서.md" --output "결과.docx" --font "Arial"
`

$3

`bash
npx markdown-to-docx --input "파일.md"
`

$3

#### 기본 사용 (input.md → output.docx)

`bash
npm start
`

#### 파일명 지정

`bash
npm start -- --input "마크다운파일.md"
`

#### 폰트 변경

`bash
npm start -- --font "나눔고딕"
`

#### 출력 파일명 지정

`bash
npm start -- --input "source.md" --output "result.docx"
`

#### 옵션 조합

`bash
npm start -- --input "문서.md" --output "결과.docx" --font "Arial"
`

$3

`bash
npm run dev -- --input "파일.md"
`

또는

`bash
npx ts-node src/cli.ts --input "파일.md"
`

$3

#### Node.js 코드에서 사용

`javascript
const { convertMarkdownToDOCX } = require("markdown-to-docx");

convertMarkdownToDOCX("input.md", "output.docx", {
fontFamily: "맑은 고딕",
verbose: true,
})
.then(() => console.log("완료!"))
.catch((error) => console.error(error));
`

#### 커스텀 DocxBuilder 사용

`javascript
const fs = require("fs");
const { parseMarkdown, DocxBuilder } = require("markdown-to-docx");

// 마크다운 파싱
const content = fs.readFileSync("input.md", "utf-8");
const elements = parseMarkdown(content, { verbose: true });

// 커스텀 빌더 생성
const builder = new DocxBuilder("Arial");

// 요소 추가
elements.forEach((element) => {
builder.addElement(element);
});

// 파일 저장
builder.save("output.docx");
`

$3

#### Node.js 코드에서 사용 (import)

`typescript
import { convertMarkdownToDOCX } from "markdown-to-docx";

async function main() {
const outputFile = await convertMarkdownToDOCX("input.md", "output.docx", {
fontFamily: "맑은 고딕",
verbose: true,
});
console.log(완료: ${outputFile});
}

main().catch(console.error);
`

#### 커스텀 DocxBuilder 사용

`typescript
import { parseMarkdown, DocxBuilder } from "markdown-to-docx";
import * as fs from "fs";

async function main() {
// 마크다운 파싱
const content = fs.readFileSync("input.md", "utf-8");
const elements = parseMarkdown(content, { verbose: true });

// 커스텀 빌더 생성
const builder = new DocxBuilder("Arial");

// 요소 추가
elements.forEach((element) => {
builder.addElement(element);
});

// 파일 저장
await builder.save("output.docx");
}

main().catch(console.error);
`

$3

`bash


로컬 npm link

cd markdown-to-docx
npm link

다른 프로젝트에서

npm link markdown-to-docx
`

지원하는 마크다운 문법

$3

`markdown


Heading 1

Heading 2

$3

#### Heading 4

##### Heading 5

###### Heading 6
`

$3

`markdown
굵은 텍스트 → Bold
_기울임 텍스트_ → Italic
코드 블록 → Code (Consolas 폰트, 배경색)
`

$3

`markdown
- 항목 1
- 항목 2
- 중첩 항목 2-1
- 중첩 항목 2-2
- 항목 3
`

$3

`markdown
- [ ] 미완료 작업
- [x] 완료된 작업
`

$3

마크다운 표준 테이블 형식을 지원합니다. 구분선은 다양한 형식이 가능합니다.

`markdown
| 열1 | 열2 | 열3 |
| ------ | ------ | ------ |
| 데이터 | 데이터 | 데이터 |
| 데이터 | 데이터 | 데이터 |
`

지원하는 구분선 형식:

- 표준: | --- | --- | --- |
- 단일 대시: | - | - | - |
- 혼합 길이: | - | --- | ----- |
- 열 정렬: | :--- | :---: | ---: |

`markdown
| 좌측 정렬 | 중앙 정렬 | 우측 정렬 |
| :-------- | :-------: | --------: |
| 왼쪽 | 가운데 | 오른쪽 |
`

$3

`markdown
링크 텍스트
`

$3

`markdown
!대체 텍스트
`

$3

`markdown
> 이것은 인용문입니다.
> 파란색 테두리와 회색 배경으로 표시됩니다.
`

$3

`markdown
첫 번째 줄
두 번째 줄 → 줄바꿈 처리
텍스트

---

텍스트 → 구분선 처리

→ 주석 제거

...

→ 태그 제거, 내용만 유지
`

프로젝트 구조

`
markdown-to-docx/
├── src/ # TypeScript 소스
│ ├── index.ts # 메인 진입점 & 라이브러리 API
│ ├── cli.ts # CLI 진입점
│ ├── markdownParser.ts # 마크다운 파싱
│ ├── inlineFormatter.ts # 인라인 포맷팅 (bold, italic, link 등)
│ └── docxBuilder.ts # DOCX 문서 생성
├── dist/ # 컴파일된 JavaScript (npm run build로 생성)
│ ├── index.js, index.d.ts # - npm 배포 시 포함
│ ├── cli.js, cli.d.ts
│ ├── markdownParser.js, markdownParser.d.ts
│ ├── inlineFormatter.js, inlineFormatter.d.ts
│ └── docxBuilder.js, docxBuilder.d.ts
├── examples/ # 사용 예제
│ ├── basic-usage.ts # TypeScript 기본 사용 예제
│ ├── advanced-usage.ts # TypeScript 고급 사용 예제
│ └── ts-usage.ts # TypeScript 라이브러리 사용 예제
├── tests/ # 테스트 마크다운 파일
│ ├── test_features.md
│ ├── test_formatting.md
│ └── test_html.md
├── build/ # 생성된 DOCX 파일 (git 제외)
├── tsconfig.json # TypeScript 설정
├── eslint.config.cjs # ESLint 설정 (v9+)
├── .prettierrc # Prettier 포맷팅 설정
├── .prettierignore # Prettier 제외 파일
├── package.json # 프로젝트 설정 & npm 스크립트
├── DEVELOPMENT.md # 개발자 문서
├── README.md # 이 파일
└── .gitignore
`

API 레퍼런스

$3

마크다운 파일을 DOCX로 변환합니다.

매개변수:

- inputFile (string): 입력 마크다운 파일 경로
- outputFile (string): 출력 DOCX 파일 경로
- options (object): 옵션
- fontFamily (string): 사용할 폰트 (기본값: '맑은 고딕')
- verbose (boolean): 상세 로그 출력 (기본값: true)

반환값:

- Promise: 생성된 파일 경로

예제:

`javascript
await convertMarkdownToDOCX("input.md", "output.docx", {
fontFamily: "Arial",
verbose: true,
});
`

$3

마크다운 텍스트를 파싱합니다.

매개변수:

- content (string): 마크다운 텍스트
- options (object): 옵션
- verbose (boolean): 상세 로그 출력 (기본값: true)

반환값:

- Array