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

2019-06-05
macgitgitbooknode.js
    

目次

概要

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

https://www.gitbook.com/

どんなものができるのか

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

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

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

https://gitbookio.gitbooks.io/documentation/index.html

検証した環境

  • 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が必要です。

https://calibre-ebook.com

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を配置すると自動で挿入されます。

参考

https://www.npmjs.com/package/gitbook-cli

https://1000ch.net/posts/2018/gitbook.html

https://qiita.com/arm_band/items/ec5bb0a0d1dec1e6da79

https://akerun.hateblo.jp/entry/2017/12/26/110102

https://kounoike.github.io/posts/2016-06-16-gitbook-pdf/

    

関連記事

Node.js で作成した REST API を Docker化
Node.jsでREST APIを作成 コンテナ化 コンテナ化定義 コンテナ化作業 参考 Node.js で作成した REST API を Docker化した際のメモです。 Node.jsでREST APIを作成 まずはNode.js…

GitLab.com のコンテナレジストリで1つのプロジェクトに複数のDockerイメージをpushする
手順 GitLab.com のコンテナレジストリで1つのプロジェクトに複数のDockerイメージをpushする方法についてのメモです。 手順 まず、gitlab.comにて適当なリポジトリを…

JSで32ビット符号付き整数に対してのビット演算でハマった
具体例 参考にしたサイト JSでサブネットマスクの計算を行おうとしたとき、ビット演算でハマりました。その時のメモです。 JSでサブネットマスクの計算 JSでビット演算子を利用する場合 3…

Gitにプロキシを設定する
プロキシを設定する 確認 Gitでプロキシを通しておくメモです。 プロキシを設定する 以下のコマンドでproxyを通します。 ※ がプロキシのURL…

プログラムの数値計算で発生する誤差の種類 丸め誤差・打ち切り誤差・桁落ち
はじめに 誤差の種類 丸め誤差 打ち切り誤差 桁落ち 情報落ち 桁溢れ誤差 参考にしたサイト コンピュータで出てくる誤差はいくつかありますが、 それらをコードに落として整理しました。 はじめに 例えば の計算の答えは 0.6666666666…

JSでサブネットマスクの計算
JSによるサブネットマスク関連の計算 IPv4アドレス文字列をNumber型に変換する CIDR と サブネットの相互変換 ネットワークアドレス と ブロードキャストアドレス クラス 改めて計算方法を整理する 参考にさせていただいたサイト JSでIPv…

Homebrew で php7.4 + Xdebug をインストール
php7.4のインストール Xdebugのインストール php.ini に追記 参考にさせていただいたサイト phpunitのカバレッジを算出を行うためにMacにHomebrewでphp7.4をインストールしようとした際の記録です。 php7.…

AWS Amplify に Next.js (SSG) で作ったアプリをデプロイする
はじめに 操作 Next.js (React) アプリの作成、Gitへのプッシュ AWS Amplifyでプロジェクト作成 参考にしたサイト この記事では、React / Next.js アプリケーションを作成し、AWS Amplify…

Typescriptに入門した
初期作業 とりあえずHello World 初期作業 typescript環境を作っていきます。 とりあえずHello World まず、次のサンプルコードを作成します。 typescriptファイルをビルドします。

Vue/Nuxt.js 触ってた人が Next.js に入門する
はじめに 実施環境 学習ガイド Create a Next.js App Navigate Between Pages ページの作成 リンク Assets, Metadata, and CSS Assets メタデータ CSS…

最新の投稿

Node.js で作成した REST API を Docker化
Node.jsでREST APIを作成 コンテナ化 コンテナ化定義 コンテナ化作業 参考 Node.js で作成した REST API を Docker化した際のメモです。 Node.jsでREST APIを作成 まずはNode.js…

JavaScriptで優先度付きキューを実装する
優先度付きキューについて ソース 参考 JavaScriptで優先度付きキュー (プライオリティキュー) を実装する 優先度付きキューについて 具体的には次のような機能があります。 キューに対して要素を優先度付きで追加 (push…

AWS Amplify で コンテナベースのデプロイを行い REST API を構築
検証した環境 やってみる 初期準備 パイプラインを確認 終了処理 参考 AWS Amplify で コンテナベースのデプロイを行い REST API を構築した際のメモです。 検証した環境 amplify 5.1.…

Pythonでソケット通信を実装しメッセージの送受信を行う
ソース server.py client.py 動かしてみる 参考 Pythonでソケット通信を実現する方法です。 ソース server.py サーバ側のソースです。 client.py…

next_permutationをJSで実装する
ソース 使い方 参考 C++で提供されている順列を生成する next_permutation のJS実装です。 ソース 順列が存在する場合はtrueを返し、そうでなければfalse…

応用情報技術者試験の合格体験記
受験時のステータス 受験結果 対策 スケジュール 午前問題 午後問題 参考書等 令和…

[JS]ラジアンから度数に度数からラジアンに変換する
コード 度数からラジアンへ ラジアンから度数へ サンプル ラジアンから度数に度数からラジアンに変換する際のスニペット。 コード 度数からラジアンへ ラジアンから度数へ サンプル

CentOS8 に Python + OpenCV をインストール
インストール テスト CentOS8 で標準で提供されているパッケージで Python + OpenCV 環境を構築する方法です。 検証した環境は CentOS8.3 (Docker) です。 インストール まず opencv…

[Perl] CentOS8 に plenv をインストール
インストール Step1 事前準備 Step2 PATHを通す (README通りにインストール) Step2 PATHを通す ($HOME以外にplenvをインストール) Step3 Perlインストール Step4 cpanmインストール CentOS…

JS/TSのclassでclass名を取得する
コード JS/TSのconstructorを利用して自分自身のクラス名を取得する際のメモ。 コード このコードの結果は次のようになります。

Tags

Dates

s-yoshiki
s-yoshiki
githubtwitterqiita
Web作ってますが、インタラクティブなプログラミングも好きです。
JavaScript / Vue / node.js / PHP / AWS / OpenCV
© 2021   404 motivation not found