GitBook 的 Word 到 Markdown：从 Word 文档发布文档 |WordToMD

GitBook 是一个流行的平台，用于使用 Markdown 创建文档站点、API 指南和知识库。如果您的文档草稿位于 Word 中，那么将它们转换为与 GitBook 兼容的 Markdown 是一个简单的过程。本指南涵盖了完整的 Word 到 GitBook 工作流程。

为什么使用 GitBook 来获取文档？

GitBook 将 Markdown 文件变成一个精美的、可搜索的文档网站，具有：

干净、专业的默认主题
全文搜索
从文件结构生成的导航侧边栏
版本控制文档的 GitHub 同步
自定义域

一旦转换为 Markdown，用 Word 编写的内容可以很好地映射到 GitBook 的页面模型。

转换 Word 文档

开始于 WordToMD:

将 .docx 文档草稿拖到转换器上
Review the Markdown output — check headings, tables, and code sections
下载 .md 文件

输出是 GitBook 直接接受的标准 Markdown。

GitBook 文件结构

GitBook 围绕一个组织内容 SUMMARY.md 文件：

# Table of Contents

* [Introduction](README.md)
* [Getting Started](getting-started/README.md)
  * [Installation](getting-started/installation.md)
  * [Configuration](getting-started/configuration.md)
* [API Reference](api/README.md)
  * [Authentication](api/authentication.md)

SUMMARY.md 中的每个项目符号都会成为 GitBook 侧栏中的一个页面。转换 Word 文档后，将它们组织成这种结构。

GitBook 中的 Frontmatter

GitBook（旧版本）不使用 YAML frontmatter — 页面标题来自第一个 H1 标题。GitBook 的较新版本 (GitBook.com) 确实接受一些 frontmatter，但安全的方法是使用第一个 # Heading 作为页面标题：

# Authentication Guide

This section describes how to authenticate with the API.

## Overview

...

标题结构

GitBook 从 H2 和 H3 标题生成页面级目录。保持层次结构干净：

H1 — 页面标题（每个文件一个）
H2 — 主要部分（出现在目录页中）
H3 — 小节

见 Markdown 标题指南标题最佳实践。

GitBook 中的表

GitBook 使用样式呈现 GFM 表。Word 文档中的表格可通过以下方式正确转换 WordToMD:

| Endpoint | Method | Description |
|---|---|---|
| `/auth/login` | POST | Authenticate user |
| `/auth/logout` | POST | End session |
| `/users/{id}` | GET | Get user profile |

对于复杂的表格场景，请参阅 Markdown 表：完整指南.

代码块

GitBook 通过语法突出显示呈现受隔离的代码块。转换后 WordToMD，正确格式化代码示例：

```bash
npm install -g gitbook-cli
gitbook init my-docs
```

GitBook 还有一个特殊的“提示”块类型用于标注：

{% hint style="info" %}
This is an information callout.
{% endhint %}

{% hint style="warning" %}
This is a warning callout.
{% endhint %}

如果您的 Word 文档突出显示了标注框，请在初始 Markdown 转换后将它们转换为 GitBook 提示块。

GitHub 同步工作流程

GitBook 支持与 GitHub 存储库同步：

创建 GitHub 存储库并添加转换后的 .md 文件
将 GitBook 连接到 GitBook 设置中的存储库
GitBook 自动从 Markdown 文件构建和发布
GitBook 中的编辑同步回 GitHub，反之亦然

这为您提供了文档的版本控制，并让您的团队通过 GitHub PR 或直接在 GitBook 的编辑器中进行协作。

有关 GitHub Markdown 的详细信息，请参阅 Word 到 GitHub Markdown.

图像

从 Word 文档导出图像（另存为→网页将图像保存到文件夹）。在具有 GitHub 同步功能的 GitBook 中，将图像提交到 assets/ or images/ 目录并引用它们： Markdown 旁边的

![Architecture Diagram](assets/architecture.png)

在 GitBook 的网页编辑器中，您可以在编辑页面时直接上传图片。

迁移完整文档集

对于从 Word 到 GitBook 的大型文档迁移：

审核 Word 文档 — 识别页面、部分和层次结构
规划SUMMARY.md结构 转换前
转换文件 with WordToMD （或批量转换适用于大容量）
创建SUMMARY.md 匹配您的计划结构
查看每一页 用于标题层次结构、表格格式和代码块
发布通过 GitBook 导入或 GitHub 同步

FAQ

GitBook 使用什么 Markdown 风格？ GitBook 使用标准 Markdown (CommonMark) 加上它自己的扩展（提示块、选项卡、嵌入块）。WordToMD 的 Markdown 输出是兼容的。

我可以将 .docx 直接导入到 GitBook 中吗？ GitBook.com 的导入功能接受 Word 文档，但输出的质量通常低于通过 Markdown 的质量。两步方法（Word→Markdown→GitBook）可以为复杂文档提供更好的结果。

如何处理跨文档链接？ 在具有 GitHub 同步功能的 GitBook 中，使用相对 Markdown 链接： [See Authentication](../api/authentication.md). GitBook resolves these to proper page links.

我的文档有 50 多个 Word 文件。有更快的工作流程吗？ 见批量将 Word 转换为 Markdown 用于自动执行转换步骤，然后编写脚本以从文件结构生成SUMMARY.md。

结论

转换 Word 到 GitBook Markdown 是一个干净的工作流程： WordToMD 处理文档转换，GitBook 的 GitHub 同步或直接导入处理发布。在 Word 中使用标准标题样式，保持表格简单，您将拥有一个快速运行的专业文档网站。