スポンサーリンク

gitbookを使ってドキュメントを生成する

スポンサーリンク
gitbookを使ってドキュメントを生成する Git
スポンサーリンク

スポンサーリンク

概要

GitBookを使ってドキュメントを生成するまでをやってみました。
なお、この記事で紹介しているのはgitbook-cliであり、クラウドサービスのGitBookはこちら↓を見て下さい。

GitBook - Document Everything!
Share knowledge, boost your team's productivity and make your users happy.

どんなものができるのか

こんなドキュメントが作れます。

デフォルトのデザインだとこんなドキュメントが作れます。

↓ ※このサイトをキャプチャしています。

Introduction | GitBook.com Documentation
Help and documentation for using GitBook.com

検証した環境

macOS mojava
nodejs 12.1.0
npm 6.9.0

nodejs npm の紹介&導入は省きます。

gitbookのインストール

npmを使ってgitbook-cliをインストールします。
コマンドを実行すると以下のようなメッセージが出てきます。

$ npm install -g gitbook-cli
/usr/local/bin/gitbook -> /usr/local/lib/node_modules/gitbook-cli/bin/gitbook.js
+ gitbook-cli@2.3.2
added 578 packages from 672 contributors in 18.22s

これを導入することによりgitbookコマンドが使えるようになります。

こちらのバージョンがインストールされました。

$ gitbook -V
CLI version: 2.3.2
Installing GitBook 3.2.3

プロジェクトの作成

プロジェクトを作成していきます。
任意のディレクトリでgitbookコマンドを叩きます。

$ mkdir gitbook_test
$ cd gitbook_test
$ gitbook init

すると REAME.md と SUMMARY.md が作成されます。

$ tree ../gitbook_test 
../gitbook_test
├── README.md
└── SUMMARY.md

ディレクトリ構成について

基本的なディレクトリ構成について紹介します。

.
├── README.md   # 概要を書く
├── SUMMARY.md   # 目次を書く
├── _book   # ビルドしたファイルが置かれるディレクトリ
├── book.json   # 設定を記述するファイル
├── docs   # マークダウンファイルを配置するディレクトリ
└── img   # マークダウンで利用する画像を配置するディレクトリ

README.md, SUMMARY.md 以外は自分で作成します。
docs や img のディレクトリ名は固定ではなく任意の名前にすることが出来ました。

ドキュメントの記述

概要とコンテンツが1ページある簡単なドキュメントを生成してみます。

docs以下にhello.mdを作成します。
imgに適当な画像を置き、
docs/hello.md

# Hello World

* 最初の投稿

![](/img/test.png)

このマークダウンではimgに配置した画像を参照しています。
このソースではルートパスで参照していますが、ビルド時には相対パスに変換されます。
なので、Webサーバのサブディレクトリに配置した場合でも正しく参照してくれるハズです。

README.md

# Introduction

* 概要のページです

test

※デフォルトではIntroductionとだけ記述がありますが、中身はなんでも良いです。

SUMMARY.md

# 概要

* [Introduction](README.md)

* [Hello World!](docs/hello.md)

日本語化

book.jsonに次のよう記述します。
book.json

{
    "language": "ja"
}

ビルドインサーバの起動

gitbookのルートディレクトリに移動し、gitbook serveでビルドインサーバを起動することが出来ます。

gitbook serve 
Live reload server started on port: 35729
Press CTRL+C to quit ...

info: 7 plugins are installed 
info: loading plugin "livereload"... OK 
info: loading plugin "highlight"... OK 
info: loading plugin "search"... OK 
info: loading plugin "lunr"... OK 
info: loading plugin "sharing"... OK 
info: loading plugin "fontsettings"... OK 
info: loading plugin "theme-default"... OK 
info: found 2 pages 
info: found 0 asset files 
info: >> generation finished with success in 0.7s ! 

Starting server ...
Serving book on http://localhost:4000

http://localhost:4000にアクセスするとマークダウンから生成されたhtmlファイルを見ることができます。
ドキュメントを更新すると変更を検知して自動でリロードしてくれる嬉しい機能がついてます。

ビルドとHTMLの生成

以下のコマンドでビルドすることができます。
実行すると次のようになります。

$ gitbook build
info: 7 plugins are installed 
info: 6 explicitly listed 
info: loading plugin "highlight"... OK 
info: loading plugin "search"... OK 
info: loading plugin "lunr"... OK 
info: loading plugin "sharing"... OK 
info: loading plugin "fontsettings"... OK 
info: loading plugin "theme-default"... OK 
info: found 2 pages 
info: found 1 asset files 
info: >> generation finished with success in 0.6s !

ビルドされたファイルは_bookの中に吐かれます。

(例)

_book
├── docs
│   └── hello.html
├── gitbook
│   ├── fonts
│   │   └── fontawesome
│   │       ├── FontAwesome.otf
│   │       ├── fontawesome-webfont.eot
│   │       ├── fontawesome-webfont.svg
│   │       ├── fontawesome-webfont.ttf
│   │       ├── fontawesome-webfont.woff
│   │       └── fontawesome-webfont.woff2
│   ├── gitbook-plugin-fontsettings
│   │   ├── fontsettings.js
│   │   └── website.css
│   ├── gitbook-plugin-highlight
│   │   ├── ebook.css
│   │   └── website.css
│   ├── gitbook-plugin-lunr
│   │   ├── lunr.min.js
│   │   └── search-lunr.js
│   ├── gitbook-plugin-search
│   │   ├── lunr.min.js
│   │   ├── search-engine.js
│   │   ├── search.css
│   │   └── search.js
│   ├── gitbook-plugin-sharing
│   │   └── buttons.js
│   ├── gitbook.js
│   ├── images
│   │   ├── apple-touch-icon-precomposed-152.png
│   │   └── favicon.ico
│   ├── style.css
│   └── theme.js
├── img
│   └── test.png
├── index.html
└── search_index.json

PDFの生成

PDFの生成にはCalibreが必要です。

calibre - E-book management
calibre: The one stop solution for all your e-book needs. Comprehensive e-book software.

mac (homebrew) の場合はbrew cask install Calibreで取得することができます。

$ gitbook pdf              
info: 7 plugins are installed 
info: 6 explicitly listed 
info: loading plugin "highlight"... OK 
info: loading plugin "search"... OK 
info: loading plugin "lunr"... OK 
info: loading plugin "sharing"... OK 
info: loading plugin "fontsettings"... OK 
info: loading plugin "theme-default"... OK 
info: found 2 pages 
info: found 1 asset files 
info: >> generation finished with success in 5.5s ! 
info: >> 1 file(s) generated

book.pdf が生成されます。

ルートにcover.jpg cover_small.jpgを配置すると自動で挿入されます。

参考

gitbook-cli
CLI to generate books and documentation using gitbook
gitbook で Markdown から PDF を生成する
gitbook で Markdown から PDF を生成する 技術書典5 への参加を目指して、執筆環境をセットアップしたのでそのメモ。今回は GitBook を使って Markdown から PDF を生成する。選択肢としては更に高機能な Re:VIEW もあるが、筆が進みやすいようにとりあえず使い慣れている Mar...
GitBookを使ってみる - Qiita
※(のコピーです。 とあるサービスのドキュメント...
gitbookで設計書を作成したら最高だった話 - フォトシンス エンジニアブログ
こんにちは。Akerunエンジニアの @ishturk です。 Akerun Advent Calendarの記事です。 今日は設計書の話です。 設計書をどんなツールで書くかは、僕らソフトウェアエンジニアの尽きない悩み(楽しみ)ですね。 最近はまったツールが最高に良かったので紹介させてください。 僕のツールに求める要件...
GitbookでPDF出力を試してみる
ちょっと最近 Markdown/asciidoc などからの PDF 作成を調べて回っている。 asciidoctor も調べたんだけど出力の微調整でうまくいかなくて行き詰っている。 というわけで、Ver.3.0.0以降でPDF出力のテーマ設定が可能になったみたいな、 GitbookIO/gitboo を試してみる。 ...
GitMac
スポンサーリンク
スポンサーリンク
スポンサーリンク
404 Motivation Not Found
タイトルとURLをコピーしました