iEdit のユーザーズマニュアルはとてもレガシーです。
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
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
ここまでくると、package.json を導入して npm script を書いた方がいいですね。ちなみに Markdown ファイルを置く <source dir> は books.json の root キーで指定可能ですが、出力先の指定はできません。Issue が上がっていました。
github.com
ともかく、ドキュメントが書けたら、GitHub に docs フォルダを含めて push します。
github.com
push したリポジトリの Settings タブを開き、GitHub Pages を有効化し設定します。
Source で master branch /docs folder を設定します。master への push が即座に反映されるため gh-pages ブランチを作成して push する方法よりも、一人作業だと手軽でよいと思います。
Google Sites のドメイン設定を解除して、Custom Domain に設定しました。Enforce HTTPS も数分で有効化することができました。
リニューアルしたサイト
イントロダクション · iEdit User's Guide
中身はほとんど変えてないし、スクリーンショットも古いのを流用しているので新しい感は薄いかもしれませんが、外側はレスポンシブなモダンな感じになりました。更新も手軽になりましたし。
Jekyll と比べても導入が楽で、手軽に公開・更新でき、PDF も生成できる GitBook はドキュメント作成環境として有力な選択肢だと思います。
