GitBook - это популярная платформа для создания сайтов документации, API руководств и баз знаний с использованием Markdown. Если ваши проекты документации живут в Word, их преобразование в GitBook-совместимые Markdown - это простой процесс. Это руководство охватывает полный Word к GitBook рабочий процесс.
Почему GitBook для документации?
GitBook превращает файлы Markdown в полированный, доступный для поиска сайт с документацией:
- Чистая, профессиональная тема по умолчанию
- Поиск полного текста
- Побочная панель навигации, сгенерированная из структуры файла
- GitHub синхронизация для документов с управляемыми версиями
- Специальные домены
Содержимое, написанное в Word, хорошо отображается в модели страницы GitBook после преобразования в Markdown.
Преобразование _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
Начнем с WordToMD:
- Перетащить проект документации .docx на преобразователь
- Проверьте Markdown выход проверьте заголовки, таблицы и разделы кода
- Загрузить файл .md
Выход стандартный Markdown, который GitBook принимает непосредственно.
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
GitBook (старинные версии) не использует YAML-фронтмат заголовки страниц происходят из первого заголовка H1. Новейшая версия GitBook (GitBook.com) принимает некоторые предварительные материалы, но безопасным подходом является использование первой версии. # Heading как заголовок страницы:
# Authentication Guide
This section describes how to authenticate with the API.
## Overview
...Структура руководящего состава
GitBook генерирует таблицу содержания на уровне страниц из заголовков H2 и H3. Держите свою иерархию чистой:
- H1 Заголовок страницы (один на файл)
- H2 Основные разделы (появляется на странице TOC)
- 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 для вызовов:
{% hint style="info" %}
This is an information callout.
{% endhint %}
{% hint style="warning" %}
This is a warning callout.
{% endhint %}Если в вашем документе Word выделены ящики для вызовов, преобразуйте их в блоки подсказок GitBook после первоначального преобразования Markdown.
GitHub Синхронизация рабочего процесса
GitBook поддерживает синхронизацию с GitHub репозиторием:
- Создать GitHub репо и добавить преобразованные .md файлы
- Подключить GitBook к репо в настройках GitBooks
- GitBook автоматически создает и публикует из файлов Markdown
- Изменения в GitBook синхронизируются обратно в GitHub, и наоборот
Это дает вам контроль над версиями ваших документов и позволяет вашей команде сотрудничать с помощью GitHub PRs или непосредственно в редакторе GitBook.
Подробности GitHub Markdown см. Word к GitHub Markdown.
Изображения
Экспортировать изображения из ваших документов Word (Сохранить как → Веб-страница сохраняет изображения в папку). В GitBook с GitHub синхронизации, привязать изображения к assets/ or images/ каталог и ссылка на них:
В веб-редакторе GitBook вы можете загружать изображения непосредственно при редактировании страниц.
Миграция полного набора документов
Для миграции большой документации с Word на GitBook:
- Проверка документов Word определить страницы, разделы и иерархию
- Планировать структуру SUMMARY.md перед преобразованием
- Конвертировать файлы with WordToMD (или преобразование партий для больших объемов)
- Создать резюме.md соответствует вашей планируемой структуре
- Проверка каждой страницы для иерархии заголовков, форматирования таблиц и блоков кодов
- Публиковать через GitBooks импорт или GitHub синхронизация
FAQ
Какой Markdown аромат использует GitBook? GitBook использует стандартный Markdown (CommonMark) плюс свои собственные расширения (блоки ссылок, вкладки, блоки встраивания). Выход Markdown от WordToMD совместим.
Могу ли я импортировать .docx непосредственно в GitBook? Функция импорта GitBook.com принимает документы Word, но часто вывод имеет более низкое качество, чем прохождение через Markdown. Двухступенчатый подход (Word → Markdown → GitBook) дает лучшие результаты для сложных документов.
Как я справляюсь с перекрестными ссылками?
В GitBook с синхронизацией GitHub используйте относительные Markdown ссылки: [See Authentication](../api/authentication.md). GitBook resolves these to proper page links.
В моей документации более 50 Word файлов. Есть ли более быстрый рабочий процесс? См. также: Перевод партии Word на Markdown для автоматизации этапа преобразования, затем напишите скрипт для генерации SUMMARY.md из структуры файла.
Заключение
Преобразование Word к GitBook Markdown является чистым рабочим процессом: WordToMD обрабатывает конвертацию документа, а GitBooks GitHub синхронизация или прямой импорт обрабатывает публикацию. Используйте стандартные стили заголовков в Word, сохраняйте таблицы простыми, и у вас будет профессиональный сайт с документацией, работающий быстро.