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

2019-06-05
macgitgitbook
    

目次

概要

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/

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

関連記事

GitHubのリポジトリをGitLabに同期する GitLabのミラーリング機能
GitLabのミラーリングについて GitHubのリポジトリをGitLabに反映する その他 参考 GitLabのミラーリング機能によりGitHubなどの外部のリポジトリとのミラーリングを行うことができます。 これを使ってGitHub…

GitLab API の 簡単な使い方
原則:アクセストークン 原則:ページネーション プロジェクトを取得する プロジェクト一覧表示 指定IDのプロジェクトを表示 その他 グループを取得する その他 ユーザの取得 ユーザ一覧 ユーザ詳細 その他、独立したAPI GitLabではREST API…

Macでも利用できるDBクライアント MySQL PostgreSQL Oracle など
デスクトップ系ツール TablePlus DBeaver MySQL Workbench Sequel pro Webアプリケーション phpMyAdmin Adminer 参考 Macで利用できるDB (MySQL PostgreSQL Oracle…

Gitの初心者向け入門資料を集めてみた
バージョン管理システムとして利用される事が多いGitですが、初心者には意外とハードルが高かったりするため、初心者向け入門資料を集めてみました。 Git入門資料 https://gist.github.com/s-yoshiki/3ef9bfde7c0b…

fswatch rsync unison を使ってリアルタイムで同期する
環境・バージョン情報等 fswatch バージョン情報 インストール fswatch + rsync で同期する fswatch + unison で同期する unisonの設定 同期コマンド 参考 fswatch + rsync or fswatch…

macOSにOpenCV4をインストール
パッケージの情報 インストール 試す with Python3 macOS (MacBook Pro 2018 13 inchi)にhomebrewを用いてOpenCVをインストールする方法。 パッケージの情報 まず、brew search と brew info…

SwitchHosts hostsの設定を変更するツール
SwitchHosts インストールする homebrew scoop それ以外 設定ファイル 参考 ローカル開発環境を利用して開発している際に、ローカルのIPに対してのホスト名をhosts…

fswatchで変更されたファイルを監視する
fswatch インストール 基本的なコマンドの使い方 試す ディレクトリを監視できるサービスfswatchをMacでインストールして使ってみました。 fswatch https://github.com/emcrisostomo/fswatch…

エンジニアなMacBookのセットアップ 開発環境の構築
ブラウザ関連 Homebrewのインストール ターミナル環境系 Hyper エディタ VSCode typora CLIツール Git 言語系 Python node.js MacBookPro…

多段SSHの設定 踏み台経由
設定 基本的なconfigの記述 基本的な踏み台経由のSSH設定 プロキシを経由して踏み台に接続するSSH設定 踏み台を経由して多段SSHを行う際の設定についてのメモ。 設定 SSHの設定はMac/Linux/WSLであればホームディレクトリ下の~/.ssh…

最新の投稿

JavaScriptの配列ショートハンド (AtCoder用)

JavaScriptでワーシャルフロイド法を実装
AtCoder ABC012 D問題 D - バスと避けられない運命 解説 実装 AtCoder ABC012 の D問題でワーシャルフロイド法が利用できる問題が出てきたので、 JavaScriptで実装しました。 AtCoder ABC012 D問題 D…

GitHub Actions で Gatsby をビルドし Amazon S3 にデプロイする
GitHub Actions について あらかじめ準備しておくもの AWS IAM ユーザを環境変数にセットする workflowの記述 ビルド バッジを利用する 終わりに 参考にしたところ Gatsbyで作った静的サイトを、GitHub Actions…

cloudinaryによる画像ファイルの管理 はじめてみる
目的 cloudinary について 他のサービスとの比較 料金プラン アカウントの登録 利用してみる ダッシュボード 画像の編集 APIベースでのアクセス 感想 参考 画像の管理や配信、さらには加工といった事ができるsaas型のcloud…

JavaScriptによる2分探索(バイナリサーチ) のサンプルコード
2分探索について ソース 参考 JavaScriptで2分探索(バイナリサーチ)を実装してみました。…

Vue.jsで作成された、ちょっと面白くて役立ちそうなサービス
UIコンポーネント VueSocial CKEditor 5 Vue.Draggable Vuetable 2 vuejs-datepicker Kalendar Vue Apexcharts Vue.js Google Charts vue-cart WebIDE…

GitHubのリポジトリをGitLabに同期する GitLabのミラーリング機能
GitLabのミラーリングについて GitHubのリポジトリをGitLabに反映する その他 参考 GitLabのミラーリング機能によりGitHubなどの外部のリポジトリとのミラーリングを行うことができます。 これを使ってGitHub…

WordPressやめます Gatsbyに移行しました
これまでのWordPress運用 なぜWordPressを捨てるのか? なぜGatsbyを利用するのか? gatsbyについて WordPressから記事の救出 移行対象記事の抽出 記事の置換 Gatsbyテーマの作成 Gatsby…

WordPressのDBから記事データを抽出する
WordPressのDB関連図 公開記事一覧の取得 タグ・カテゴリの取得 サムネイルの取得 おまけ: PHPスクリプト化しました 参考にしたところ WordPressにため込んだデータMarkdown化しGatsby…

ハイフンとかマイナスとかダッシュとか

Tags

Dates

© 2020   404 motivation not found