Word đến Static Site Generator: Chuyển đổi Docs cho Jekyll, Hugo, và Astro

Các máy tạo trang web tĩnh (SSG) như Jekyll, Hugo, Astro và Eleventy sử dụng các tệp Markdown để xây dựng trang web. Nếu nhóm nội dung của bạn viết bằng Word, chuyển đổi nội dung đó thành Markdown là bước đầu tiên quan trọng. Hướng dẫn này bao gồm toàn bộ Word đến vị trí tĩnh quy trình làm việc.

Quá trình làm việc cốt lõi

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

Mỗi mũi tên là một sự biến đổi.

1. WordToMD chuyển đổi .docx → .md
2. Hệ thống xây dựng SSG của bạn đọc .md và tạo HTML
3. Một CDN hoặc nền tảng lưu trữ phục vụ HTML

Thêm nội dung

Máy phát điện địa điểm tĩnh yêu cầu YAML mặt tiền ở đầu mỗi tệp Markdown. Sau khi chuyển đổi với WordToMD, thêm một khối tiền đề trước nội dung:

Jekyll / 11

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

Hugo

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

Astro

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

Tổ chức tệp

SSG mong đợi các tập tin nội dung trong thư mục cụ thể:

Khớp với quy ước tên tập tin cho SSG của bạn. Jekyll là người nghiêm khắc nhất. 2026-05-25-word-to-static-site.md.

Tiêu đề và cấu trúc nội dung

Màn hình SSG # Heading 1 là tiêu đề chính của trang. Kể từ khi title frontmatter field đã xác định tiêu đề trang, sử dụng H2 (##) như tiêu đề nội dung cấp cao nhất của bạn và tránh H1 trong cơ thể.

Trước khi chuyển đổi, kiểm tra xem tài liệu Word của bạn chỉ sử dụng tiêu đề 1 cho tiêu đề tài liệu, và tiêu đề 2 cho các phần chính. Xem thêm Markdown Hướng dẫn tiêu đề cho các chi tiết.

Hình ảnh trong các trang web tĩnh

Hình ảnh từ Word tài liệu cần phải là:

1. Xuất khẩu từ Word (Save As → Trang web sao chép hình ảnh vào thư mục)
2. Được đặt trong thư mục tài sản tĩnh của SSG của bạn (e.g, public/images/ cho Astro/Next.js, assets/images/ cho Jekyll)
3. Đề cập đến trong Markdown:

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

Bảng

Word bảng chuyển đổi thành GFM từ vựng thông qua WordToMD. All major SSGs render GFM tables. See Markdown Bảng: Hướng dẫn đầy đủ.

Các khối mã

Đối với tài liệu kỹ thuật, sử dụng các khối mã được bao vây với mã nhận dạng ngôn ngữ để làm nổi bật cú pháp:

```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.