Word đến Markdown cho GitBook: xuất bản tài liệu từ Word Docs.

GitBook là một nền tảng phổ biến để tạo các trang tài liệu, API hướng dẫn, và cơ sở kiến thức sử dụng Markdown. Nếu các bản thảo tài liệu của bạn sống trong Word, chuyển đổi chúng thành GitBook tương thích Markdown là một quá trình đơn giản. Hướng dẫn này bao gồm toàn bộ Word đến GitBook quy trình làm việc.

Tại sao GitBook cho Tài liệu?

GitBook biến các tệp Markdown thành một trang tài liệu có thể tìm kiếm được với:

Một chủ đề mặc định sạch sẽ, chuyên nghiệp
Tìm kiếm toàn văn bản
Bảng bên điều hướng được tạo từ cấu trúc tệp của bạn
GitHub đồng bộ hóa cho các tài liệu được kiểm soát phiên bản
Địa chỉ tùy chỉnh

Nội dung được viết trong Word phù hợp với mô hình trang của GitBook khi được chuyển đổi thành Markdown.

Chuyển đổi Word tài liệu

Bắt đầu với WordToMD:

Kéo bản phác thảo tài liệu .docx của bạn vào bộ chuyển đổi
Xem lại Markdown đầu ra kiểm tra tiêu đề, bảng và phần mã
Tải tệp .md

Sản xuất là Markdown tiêu chuẩn mà GitBook chấp nhận trực tiếp.

GitBook Cấu trúc tệp

GitBook sắp xếp nội dung xung quanh một SUMMARY.md file định nghĩa cấu trúc điều hướng:

# 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)

Mỗi viên đạn trong SUMMARY.md trở thành một trang trong thanh bên GitBook của bạn. Sau khi chuyển đổi các tài liệu Word của bạn, sắp xếp chúng thành cấu trúc này.

Vấn đề đầu tiên trong GitBook

GitBook (phiên bản cũ) không sử dụng YAML frontmatter tiêu đề trang đến từ tiêu đề H1 đầu tiên. GitBooks phiên bản mới hơn (GitBook.com) không chấp nhận một số mặt tiền, nhưng cách tiếp cận an toàn là sử dụng đầu tiên # Heading là tiêu đề trang:

# Authentication Guide

This section describes how to authenticate with the API.

## Overview

...

Cấu trúc ban đầu

GitBook tạo ra một bảng nội dung ở cấp trang từ tiêu đề H2 và H3. Giữ trật tự của bạn sạch sẽ:

H1 Tiêu đề trang (một trên mỗi tập tin)
H2 Các phần chính ( xuất hiện trong trang TOC)
H3 Các tiểu mục

Xem thêm Markdown Hướng dẫn tiêu đề cho tiêu đề thực tiễn tốt nhất.

Bảng trong GitBook

GitBook hiển thị GFM bảng với phong cách. Bảng từ tài liệu Word của bạn chuyển đổi chính xác thông qua WordToMD:

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

Đối với các kịch bản bảng phức tạp, xem Markdown Bảng: Hướng dẫn đầy đủ.

Các khối mã

GitBook hiển thị các khối mã được bao vây với đánh dấu cú pháp. Sau khi chuyển đổi với WordToMD, định dạng các mẫu mã đúng cách:

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

GitBook cũng có một loại khối Hint đặc biệt cho các cuộc gọi:

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

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

Nếu tài liệu Word của bạn đã làm nổi bật các hộp gọi, chuyển đổi chúng thành các khối gợi ý GitBook sau khi chuyển đổi Markdown ban đầu.

GitHub Đồng bộ hóa dòng công việc

GitBook hỗ trợ đồng bộ hóa với kho lưu trữ GitHub:

Tạo một GitHub repo và thêm các tệp .md đã chuyển đổi của bạn
Kết nối GitBook với repo trong cài đặt GitBooks
GitBook tự động xây dựng và xuất bản từ các tệp Markdown
Các chỉnh sửa trong GitBook đồng bộ lại với GitHub, và ngược lại

Điều này cung cấp cho bạn quyền kiểm soát phiên bản cho tài liệu của bạn và cho phép nhóm của bạn hợp tác thông qua GitHub PR hoặc trực tiếp trong trình soạn thảo GitBook.

Đối với GitHub Markdown chi tiết, xem Word đến GitHub Markdown.

Hình ảnh

Xuất khẩu hình ảnh từ tài liệu Word của bạn (Save As → Trang web lưu hình ảnh vào thư mục). Trong GitBook với GitHub đồng bộ, tham gia các hình ảnh để một assets/ or images/ thư mục và tham khảo chúng:

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

Trong GitBooks web editor, bạn có thể tải lên hình ảnh trực tiếp khi chỉnh sửa trang.

Di chuyển bộ tài liệu đầy đủ

Để di chuyển tài liệu lớn từ Word sang GitBook:

Kiểm tra các tài liệu Word xác định các trang, phần và phân cấp
Kế hoạch cấu trúc SUMMARY.md trước khi chuyển đổi
Chuyển đổi tệp with WordToMD (hoặc chuyển đổi lô đối với khối lượng lớn)
Tạo SUMMARY.md phù hợp với cấu trúc dự định của bạn
Xem lại mỗi trang Đối với phân cấp tiêu đề, định dạng bảng và khối mã
Báo cáo thông qua GitBooks nhập hoặc GitHub đồng bộ

FAQ

Markdown sử dụng hương vị nào? GitBook sử dụng Markdown tiêu chuẩn (CommonMark) cộng với các phần mở rộng của riêng nó (các khối gợi ý, tab, các khối nhúng). Các Markdown đầu ra từ WordToMD là tương thích.

Tôi có thể nhập .docx trực tiếp vào GitBook không? Tính năng nhập GitBook.coms chấp nhận các tài liệu Word, nhưng kết quả thường có chất lượng thấp hơn so với Markdown. Cách tiếp cận hai bước (Word → Markdown → GitBook) mang lại kết quả tốt hơn cho các tài liệu phức tạp.

Làm thế nào để tôi xử lý các liên kết chéo tài liệu? Trong GitBook với GitHub đồng bộ, sử dụng liên kết Markdown tương đối: [See Authentication](../api/authentication.md). GitBook resolves these to proper page links.

Tài liệu của tôi có hơn 50 tệp Word. Có quy trình làm việc nhanh hơn không? Xem thêm Batch Convert Word to Markdown để tự động hóa bước chuyển đổi, sau đó viết một kịch bản để tạo SUMMARY.md từ cấu trúc tệp.

Kết luận

Chuyển đổi Word đến GitBook Markdown là một dòng công việc sạch: WordToMD xử lý chuyển đổi tài liệu, và GitBooks GitHub đồng bộ hoặc nhập trực tiếp xử lý xuất bản. Sử dụng các kiểu tiêu đề tiêu chuẩn trong Word, giữ cho bảng của bạn đơn giản, và bạn sẽ có một trang tài liệu chuyên nghiệp chạy nhanh chóng.