GitBook + GitHub Pages でレガシードキュメントを移行

iEdit のユーザーズマニュアルはとてもレガシーです。

以前 Google Sites に引っ越そうと思って、サイト作ってカスタムドメイン設定してたのですが、リリースノートを更新するのみで放置して何年も経ってしまいました。その間 Google Sites もリニューアルされ HTTPS 対応もしましたが、WYSIWYG に寄り過ぎていて構造化されたドキュメントを書くプラットフォームとしてはちょっと・・という気がします。

最近、GitBook でドキュメントを Markdown で記述して静的コンテンツを公開できることを知り移行作業をしてみました。

GitBook の CLI をインストール

$ npm install gitbook-cli -g

プロジェクトを作成

$ mkdir iedit-doc
$ cd iedit-doc
$ gitbook init

空ディレクトリの場合、SUMMARY.md / README.md が生成されます。SUMMARY.md にドキュメントの構造を記述します。

# Summary

* [イントロダクション](README.md)
* [インストール](overview/install.md)
* [ノードの作成と編集](editing/edit_node.md)
 * [ノード作成](editing/edit_node.md#ノード作成)
 * [ノード編集](editing/edit_node.md#ノード編集)
* [リンクの作成と編集](editing/edit_link.md)
 * [リンク作成](editing/edit_link.md)
 * [リンク編集](editing/edit_link.md)
* [インポート・エクスポート](features/import_export.md)
* [検索](features/search.md)
* [メニューコマンド](features/menu.md)
* [各種設定](settings/README.md)
 * [オプション設定](settings/option_settings.md)
 * [ファイルタイプの登録・削除](settings/filetype_registry.md)
* [リリースノート](releasenotes/README.md)

README.md が index.html に変換されます。

SUMMARY.md が決まったら gitbook init を再実行すると、フォルダ構成と必要なファイルを作ってくれます。あとは、書きながら調整していくのがよいでしょう。

book.json を追加して、ドキュメントのタイトルや GitBook のバージョン設定、サイドバーのリンクなどを記述します。plugins に GitBook のプラグイン (実体は NPM モジュール) を指定できます。

{
    "title": "iEdit User's Guide",
    "description": "",
    "plugins": ["expandable-chapters", "ga"],
    "language": "ja",
    "gitbook": ">= 3.0.0",
    "links": {
        "sidebar": {
            "kondoumh.com": "https://kondoumh.com/software/iedit/"
        }
    },
    "pluginsConfig": {
        "ga": {
            "token": "UA-XXXXXXX-X"
        }
    }
}

plugins でプラグインを指定して以下のコマンドでプラグインのインストールが可能です。

$ gitbook install

NPM モジュールなので package.json を記述して npm install でもインストール可能です。その場合は、パッケージ名のプレフィクス gitbook-plugin- が必要になります。

サイドバーの見出しを折りたたむことができる expandable-chapters プラグインと Google Analytics のトラッキングコードを埋め込む ga プラグインを追加してみました。

www.npmjs.com

他にも YouTube の動画を組み込むプラグインなど色々と提供されてます。

ローカルでブラウザでプレビューしながら Markdown を書いていけます。

$ gitbook serve

localhost:3000 にアクセスすると、サイドバー付きのページを確認できます。

この状態で、既存の HTML から内容をコピペ＆リライトしながら移行していきました。

ある程度できたところで公開先を検討。最初これまで通り kondoumh.com に配置することも考えましたが、リリースノートも移行して旧 Google Sites サイトを廃止しつつ URL が変らないようにしたいということで独立サイトにすることにしました。GitHub Pages は独自ドメインと HTTPS に対応していて GitBook ドキュメントも簡単に公開できることを知り、渡りに船ということで GitHub Pages を使うことに決定。

ライブリロード中に HTML の変換は随時やってくれますが、シンタックスエラー等でちゃんと反映されてない可能性もありますので、最終的に build します。

$ gitbook build

デフォルトの出力先は、_book ですが、GitHub Pages のお手軽設定だと docs にしておくのがよいです。その場合は、以下のようにします。

$ gitbook build <source dir> ./docs

ついでですが、ライブプレビューでも build と同じ引数で起動した方がいいでしょう。

$ gitbook serve <source dir> ./docs

ちなみに Markdown ファイルを置く <source dir> は books.json の root キーで指定可能ですが、出力先の指定はできません。Issue が上がっていました。

github.com

最終的に package.json で管理するようにしました。gitbook-cli も global ではなく devDependencies に入れて scripts で serve / build するようにしています。

{
  "name": "iedit-doc",
  "version": "1.0.0",
  "description": "iEdit User's Guide published by GitBook",
  "directories": {
    "doc": "docs"
  },
  "dependencies": {
    "gitbook-plugin-ga": "^1.0.1",
    "gitbook-plugin-expandable-chapters": "^0.2.0"
  },
  "devDependencies": {
    "gitbook-cli": "^2.3.2"
  },
  "scripts": {
    "serve": "gitbook serve ./ ./docs",
    "build": "gitbook build ./ ./docs"
  },
   :