もうWordで疲弊しない!gitbook-cliでマニュアルを作成する
みなさんマニュアルは作成してますか?今回はテキストベースでマニュアルを作成する手順の紹介です。マニュアルもビルドしましょう。
Gitbookとは
markdown記法で書かれたテキストファイルをhtmlにビルドすることができるツールです。Calibreというツールをインストールするとpdfやepub、mobiなどの形式も出力できるようになります。
gitbook-cliとは
gitbook-cliはgitbookの作成を支援するコマンドラインツールです。ブラウザによるリアルタイムプレビューやビルド結果の出力などができます。
gitbook-cliのインストール
gitbook-cliはnpm(node.jsのパッケージマネージャ)を使ってインストールすることができます。
|
1 |
npm install -g gitbook |
これだけです。
リポジトリを初期化する
カレントディレクトリをgitbookリポジトリと認識させるために以下のコマンドを入力します。
|
1 2 3 4 5 6 7 8 9 10 11 |
$ mkdir test $ cd test $ gitbook init info: init book at C:\Users\v\Documents\test info: detect structure from SUMMARY (if it exists) info: create SUMMARY.md info: create README.md info: initialization is finished Done, without error |
Windowsの場合dir、Linuxの場合lsコマンドを入力すると、ファイルが2つ作成されているのがわかります。
|
1 2 3 4 |
2016/02/06 13:34 <DIR> . 2016/02/06 13:34 <DIR> .. 2016/02/06 13:34 15 README.md 2016/02/06 13:34 10 SUMMARY.md |
「.md」拡張子はmarkdownの略です。中身はただのテキストファイルです。
README.mdの中身の中身を確認しましょう。markdownの記法で先頭に「# 」記号は見出し1(HTMLでいうh1タグ)を表しています。
|
1 |
# Introduction |
SUMMARY.mdの中身も確認しましょう。見出しのみ書かれたシンプルなテキストファイルです。
|
1 |
# Summary |
次にこのファイルをプレビューしてみましょう。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
$ gitbook serve Live reload server started on port: 35729 Press CTRL+C to quit ... info: loading book configuration....OK info: load plugin gitbook-plugin-highlight ....OK info: load plugin gitbook-plugin-search ....OK info: load plugin gitbook-plugin-sharing ....OK info: load plugin gitbook-plugin-fontsettings ....OK info: load plugin gitbook-plugin-livereload ....OK info: >> 5 plugins loaded info: start generation with website generator info: clean website generatorOK info: generation is finished Starting server ... Serving book on http://localhost:4000 |
次にコマンド入力後に表示されたURLにブラウザでアクセスします。
するとシンプルなビューワーが表示されました。ディレクトリを見ると新たに「_book」ディレクトリが生成されています。ここにビルド結果が格納されています。gitにコミットするときはこのビルド結果をgitignoreに含めると良いでしょう。
次にSUMMARYをもうちょっと目次っぽくしてみましょう。
|
1 2 3 4 5 6 7 |
# Summary * [お布団について](./お布団について.md) * [第1布団速度](./第1布団速度.md) * [第2布団速度](./第2布団速度.md) |
目次ができました。リンク切れ状態のためリンクがグレーアウト表示になっています。
リンク先のページを追加します。テキストファイルを追加するだけです。
|
1 2 3 4 |
# 第1布団速度 --- お布団から一度出て、用を済ませ、二度寝する際に必要な速度。外気温とお布団内温度との差の2乗に比例する。 |
リンクが動作するようになりました。リンクをクリックしてみます。
表示されましたね。これでマニュアルでも小説でもガンガン書き込んでいけますね。
画像はどうするのか
画像もmarkdownの記法で参照できます。imgディレクトリを作成してfuton.pngを配置しました。更に、markdownファイルに以下を記述します。
|
1 |
 |
画像が表示できましたね。
(多分)続きます。