Word to Static Site Generator: Jekyll, Hugo, and Astro를 위한 문서 변환

Jekyll, Hugo, Astro, Eleventy와 같은 정적 사이트 생성기 (SSG) 는 Markdown 파일을 사용하여 웹 사이트를 구축합니다. 만약 여러분의 컨텐츠 팀이 Word로 글을 쓰면, 그 컨텐츠를 Markdown로 변환하는 것이 중요한 첫 번째 단계입니다. 이 가이드 는 전체 Word 정적 사이트로 작업 흐름.

핵심 업무 흐름

Word (.docx) → Markdown (.md) → SSG build → HTML website

각 화살표는 변신입니다.

1. WordToMD 개종자 .docx → .md
2. SSG 빌드 시스템은 .md를 읽고 HTML를 생성합니다.
3. CDN 또는 호스팅 플랫폼은 HTML를 서비스합니다.

앞면 을 추가 하는 것

정적 사이트 생성기는 YAML 전면 각 Markdown 파일의 상단에 있습니다. 변환 후 WordToMD, 내용 앞부분을 추가합니다:

제킬 / 11

---
layout: post
title: "Your Document Title"
date: 2026-05-25
categories: [tutorial, documentation]
tags: [word, markdown]
permalink: /blog/your-document/
---

호고

---
title: "Your Document Title"
date: 2026-05-25
draft: false
tags: ["tutorial", "documentation"]
slug: "your-document"
---

아스트로

---
title: "Your Document Title"
date: 2026-05-25
description: "A brief description for SEO."
tags: ["tutorial", "documentation"]
draft: false
---

파일 조직

SSG는 특정 디렉토리에 있는 컨텐츠 파일을 기대합니다.

SSG의 파일 이름과 일치합니다. 제킬은 가장 엄격하다. 2026-05-25-word-to-static-site.md.

제목 및 내용 구조

SSG 디스플레이 # Heading 1 페이지의 주요 제목으로. 그 이후로 title frontmatter 필드는 이미 페이지 타이틀을 정의하고, H2를 사용합니다 (##H1를 피하고, H1를 가장 높은 수준의 내용으로 사용하세요.

변환 전에, 당신의 워드 문서는 문서 제목에 대한 제목 1만 사용하고, 주요 섹션에 대한 제목 2를 사용하는지 확인하십시오. 본문 Markdown 제목 안내서 세부 사항에 대한 것입니다.

정적 사이트의 이미지

Word 문서의 이미지는:

1. Word에서 출력 (Save As → Web Page 복사된 이미지)
2. SSG의 정적 자산 디렉토리에 (e.g, public/images/ Astro/Next.js의 경우 assets/images/ 제킬 (Jekyll)
3. Markdown에서 참조:

![Diagram description](/images/diagram.png)

표

Word 테이블을 GFM 문법으로 변환 WordToMD. All major SSGs render GFM tables. See Markdown 표: 완전한 안내.

코드 블록

기술 문서의 경우, 문법을 강조하는 언어 식별자를 가진 울타리 코드 블록을 사용한다.

```python
def convert_document(filepath):
    with open(filepath, 'rb') as f:
        return mammoth.convert_to_markdown(f).value

See [Markdown Code Blocks Guide](/blog/markdown-code-blocks-guide) for all supported languages.

## Validating Markdown Before Build

Before running your SSG build, validate your converted Markdown:

- **markdownlint** — Checks for style consistency and errors
- **Vale** — Prose linting for technical writing
- **Your SSG's dev server** — The fastest way; run `hugo serve`, `jekyll serve`, or `astro dev` and check the rendered output

## Batch Conversion for Large Content Migrations

If you're migrating an existing Word-based content library to an SSG:

1. Use [WordToMD](/#converter) for individual files
2. For dozens of files, see [Batch Convert Word to Markdown](/blog/batch-convert-word-to-markdown) for command-line tools
3. Write a script to add frontmatter and rename files to your SSG's convention

A Python or Node.js script can automate the frontmatter injection after batch conversion.

## SSG-Specific Tips

### Jekyll
- Filename must include the date: `2026-05-25-your-slug.md`
- Use `categories:` for site navigation
- Liquid template tags conflict with certain curly-brace content in Markdown — escape with `{% raw %}...{% endraw %}`

### Hugo
- Hugo has strict frontmatter validation — required fields depend on your theme
- Use `hugo new content/posts/slug.md` to create a properly templated file, then paste converted content

### Astro
- Uses Content Collections with schema validation
- Ensure frontmatter fields match the schema in `src/content/config.ts`
- Astro's MDX support allows components inside Markdown if needed

### Eleventy
- Most flexible SSG — any .md file in any directory is content
- Frontmatter format is configurable (YAML, TOML, JSON)

## FAQ

**Do I need to convert each Word file manually?**
For a few files, manual conversion with [WordToMD](/#converter) is fastest. For a whole content library, [batch conversion](/blog/batch-convert-word-to-markdown) makes more sense.

**My SSG build fails after importing converted Markdown. What's wrong?**
Check for: (1) missing required frontmatter fields, (2) unescaped special characters in frontmatter values, (3) smart quotes in frontmatter strings (replace with straight quotes).

**Can Word documents become MDX files for React-based SSGs?**
Yes. Convert to standard Markdown first, rename to .mdx, then add React component imports at the top if needed. See the basics in [What Is Markdown](/blog/what-is-markdown-guide).

**Which SSG is best for a team that writes in Word?**
If your team is non-technical and writes in Word, a headless CMS (like Contentful or Sanity) with Markdown support may be a better fit than a file-based SSG. The Word → Markdown workflow works well for developers and hybrid teams.

## Conclusion

Static site generators are an excellent home for content that starts in Word. [WordToMD](/#converter) handles the conversion step; your SSG handles the publishing step. Add frontmatter, organize your files per the SSG's conventions, and you have a content pipeline that scales.