しびら

技術ネタのメモとか。

もうWordで疲弊しない!gitbook-cliでマニュアルを作成する

   

gitbook

みなさんマニュアルは作成してますか?今回はテキストベースでマニュアルを作成する手順の紹介です。マニュアルもビルドしましょう。

Gitbookとは

markdown記法で書かれたテキストファイルをhtmlにビルドすることができるツールです。Calibreというツールをインストールするとpdfやepub、mobiなどの形式も出力できるようになります。

gitbook-cliとは

gitbook-cliはgitbookの作成を支援するコマンドラインツールです。ブラウザによるリアルタイムプレビューやビルド結果の出力などができます。

gitbook-cliのインストール

gitbook-cliはnpm(node.jsのパッケージマネージャ)を使ってインストールすることができます。

これだけです。

リポジトリを初期化する

カレントディレクトリをgitbookリポジトリと認識させるために以下のコマンドを入力します。

Windowsの場合dir、Linuxの場合lsコマンドを入力すると、ファイルが2つ作成されているのがわかります。

「.md」拡張子はmarkdownの略です。中身はただのテキストファイルです。

README.mdの中身の中身を確認しましょう。markdownの記法で先頭に「# 」記号は見出し1(HTMLでいうh1タグ)を表しています。

SUMMARY.mdの中身も確認しましょう。見出しのみ書かれたシンプルなテキストファイルです。

次にこのファイルをプレビューしてみましょう。

次にコマンド入力後に表示されたURLにブラウザでアクセスします。

2016-02-06

するとシンプルなビューワーが表示されました。ディレクトリを見ると新たに「_book」ディレクトリが生成されています。ここにビルド結果が格納されています。gitにコミットするときはこのビルド結果をgitignoreに含めると良いでしょう。

次にSUMMARYをもうちょっと目次っぽくしてみましょう。

2016-02-06 (1)

目次ができました。リンク切れ状態のためリンクがグレーアウト表示になっています。

リンク先のページを追加します。テキストファイルを追加するだけです。

2016-02-06 (2)

リンクが動作するようになりました。リンクをクリックしてみます。

2016-02-06 (3)

表示されましたね。これでマニュアルでも小説でもガンガン書き込んでいけますね。

画像はどうするのか

画像もmarkdownの記法で参照できます。imgディレクトリを作成してfuton.pngを配置しました。更に、markdownファイルに以下を記述します。

 

2016-02-06 (4)画像が表示できましたね。

(多分)続きます。

 - 未分類 , , ,