Word to Markdown for GitBook: Word Docsからドキュメントを公開する

GitBookは, Markdownを使用してドキュメントサイト, APIガイド,および知識ベースを作成するための人気のあるプラットフォームです. Wordでドキュメントのドラフトが実行されている場合, GitBookと互換性のある Markdownに変換することは簡単です. このガイドでは Word に GitBook ワークフロー

なぜ GitBook は文書化のために適用されますか

GitBook は Markdown ファイルを,検索可能なドキュメンテーションサイトに変換します:

クリアでプロのデフォルトのテーマ
全文検索
ファイル構造から生成されたナビゲーションサイドバー
GitHub バージョン制御ドックスの同期
カスタムドメイン

Word で書かれたコンテンツは Markdown に変換された後に GitBook のページモデルにうまくマップされます.

Word ドキュメントを変換する

始めよう 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サイドバーのページになります. この構造にそれらを整理します.

プレート・マター

GitBook (レガシーバージョン) は YAML フロントマターを使用していませんページタイトルは最初のH1ヘッドから来ている. GitBookの新しいバージョン (GitBook.com) は,いくつかのフロントマターを受け入れるが,安全なアプローチは,最初の使用である # Heading ページタイトルとして:

# Authentication Guide

This section describes how to authenticate with the API.

## Overview

...

部署構造

GitBookは H2 と H3 のタイトルからページレベルのコンテンツの表を生成します. 階層を清潔に保つこと

H1 ページタイトル (ファイルごとに1個)
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 style="info" %}
This is an information callout.
{% endhint %}

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

初期マークダウン変換後に GitBook ヒントブロックに変換します.

GitHub 同期ワークフロー

GitBook は GitHub リポジトリとの同期をサポートします:

GitHub レポを作成し,変換された .md ファイルを追加します.
GitBook を GitBooks の設定のレポに接続する
GitBook は Markdown ファイルから自動的に作成および公開します
GitBook の編集は GitHub に同期し,逆にもなります.

GitHub PRやGitBookのエディターで直接協力することができます.

GitHub Markdownの詳細については,参照 Word から GitHub Markdown.

画像

Word ドキュメントから画像をエクスポートします (Save As → Web Page は画像をフォルダーに保存します). GitHubとの GitBook シンクでは,画像を assets/ or images/ ディレクトリと参照:

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

GitBookのウェブエディターでは,ページを編集する際に直接画像をアップロードできます.

完全なドキュメントセットを移行する

Word から GitBook に大規模なドキュメント移行の場合:

Word 文書の監査 ページ,セクション,階層を特定する
SUMMARY.md構造を計画する 変換前に
ファイル変換 with WordToMD (またはバッチ変換大量の場合)
SUMMARY.mdを作成する 計画された構造と一致する
各ページを見直す タイトル階層,表のフォーマット,コードブロックについて
公開する GitBooks インポートまたは GitHub シンク経由で

FAQ

GitBookはどのような Markdown フレームを使っているのでしょうか? GitBookは標準 Markdown (CommonMark) を使用し,独自の拡張子 (ヒントブロック,タブ,埋め込みブロック) を使用します. WordToMDからの Markdown 出力は互換性がある.

GitBook に直接 .docx をインポートできますか? GitBook.comのインポート機能は Wordドキュメントを受け入れますが,出力は Markdownを通過するよりも低品質です. 2段階のアプローチ (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の標準的なヘッディングスタイルを使用し,テーブルをシンプルに設定し,プロのドキュメントサイトを素早く稼働させることができます.

なぜ GitBook は 文書化 の ため に 適用 さ れ ます か