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 中使用標準標題樣式，保持表格簡單，您將擁有一個快速執行的專業文件網站。