GitBookをGitHub Pagesにアップロード


はずかしながら、いまさらながらにgitbookを試して見たくて、 GitHub Pagesと連携させてみました。werckerへの連携も考えましたが、当面は手作業で対応してみます。


🐯 GitBookとは?

GitBook · Documentation made easy

GitリポジトリベースでMarkdownを書いていくと電子書籍を作成できるサービスです。
ベースがGitリポジトリですので、慣れたGitのワークフローで複数人で協力して作業できるのが魅力です。

🗽 gitbookのインストール

まずは、gitbookのコマンドラインツールをインストールします。

npm install -g gitbook-cli

これはラッパですので、これで gitbook help など何かコマンドを実行するとgitbookの最新版がインストールされます。

🚌 gitbook環境構築

次のコマンドでgitbookの初期状態のフォルダが作成されます。

gitbook init

😼 gitbookの表示確認

gitbook serve
Live reload server started on port:
...
Starting server ...
Serving book on http://localhost:4000

http://localhost:4000 にアクセスすると表示確認できます!

🚕 gitbookの編集

GitBookのコンテンツ編集などに関する情報は、公式ドキュメントの『GitBook Documentation』がわかりやすいです!

🍄 PDFに変換してみる

まずは Calibre というツールをインストールします。

brew cask install calibre

次に、pdfでの変換コマンドを実行します。

gitbook pdf . gitbook.pdf

gitbook.pdf が生成されました!

🍣 GitHub Pagesの設定

🐠 GitHub PagesへのPush

まずはプロジェクト直下に package.json を作成。

{
"name": "PROJECT_NAME",
"version": "1.0.0",
"private": true,
"description": "PROJECT_DESCRIPTION",
"main": "index.js",
"scripts": {
"init": "gitbook init",
"start": "gitbook serve",
"build": "gitbook build",
"publish": "gh-pages -d _book -m 'Auto publish book'"
},
"devDependencies": {
"gh-pages": "^0.12.0",
"gitbook-cli": "^2.3.0"
}
}

npmのライブラリを npm install で導入。

次のコマンドで gh-pages に対象フォルダをpush。

npm build && npm publish

実際にgitbookを利用していく際には、 About this documentation · GitBook Toolchain Documentation がおすすめです。
gitbookのパラメータの情報やカスタマイズの方法などが細かく記載されています!

🗻 (おすすめプラグイン) gitbook-summary

imfly/gitbook-summary: A command line tool to generate a summary.md for GitBook

GitBookのSUMMARYを自動生成してくれるプラグインです。
ちなみに、日本語を含むURLの場合は、macで変換すると UTF-8-MAC になるため、公開した際にUTF-8が使われておかしくなるパターンに注意してください。
そんなときは、nkf で変換するとよいかも。

brew install nkf
nkf -w --ic=utf8-mac --overwrite *.md

😀 (おすすめプラグイン) gitbook-plugin-anchor-navigation

🎳 (Tips) .bookignore

文章生成で不要なファイルは .bookignore に追加しておくと gitbook build の際に無視してくれます。

🏀 (Tips) S3 / Route53 / Cloud Frontの活用

今回は断念しましたが、 S3 + route53 + CloudFrontも簡単に利用できそうです。

🎃 (Tips) package.jsonのライブラリを最新にする

npm-check-updates というライブラリで簡単に最新にアップデートできます。

npm install -g npm-check-updates
npm-check-updates -u
npm update

これはかなり便利。

😎 (Tips) book.jsonのサンプル

book.jsonのサンプルです。助かります!

{
// Folders to use for output
// Caution: it overrides the value from the command line
// It's not advised this option in the book.json
"output": null,
// Generator to use for building
// Caution: it overrides the value from the command line
// It's not advised this option in the book.json
"generator": "site",
// Book metadats (somes are extracted from the README by default)
"title": null,
"description": null,
"isbn": null,
// For ebook format, the extension to use for generation (default is detected from output extension)
// "epub", "pdf", "mobi"
// Caution: it overrides the value from the command line
// It's not advised this option in the book.json
"extension": null,
// Plugins list, can contain "-name" for removing default plugins
"plugins": [],
// Global configuration for plugins
"pluginsConfig": {
"fontSettings": {
"theme": "sepia", "night" or "white",
"family": "serif" or "sans",
"size": 1 to 4
}
},
// Variables for templating
"variables": {},
// Links in template (null: default, false: remove, string: new value)
"links": {
// Custom links at top of sidebar
"sidebar": {
"Custom link name": "https://customlink.com"
},
// Sharing links
"sharing": {
"google": null,
"facebook": null,
"twitter": null,
"weibo": null,
"all": null
}
},
// Options for PDF generation
"pdf": {
// Add page numbers to the bottom of every page
"pageNumbers": false,
// Font size for the fiel content
"fontSize": 12,
// Paper size for the pdf
// Choices are [u’a0’, u’a1’, u’a2’, u’a3’, u’a4’, u’a5’, u’a6’, u’b0’, u’b1’, u’b2’, u’b3’, u’b4’, u’b5’, u’b6’, u’legal’, u’letter’]
"paperSize": "a4",
// Margin (in pts)
// Note: 72 pts equals 1 inch
"margin": {
"right": 62,
"left": 62,
"top": 36,
"bottom": 36
},
//Header HTML template. Available variables: _PAGENUM_, _TITLE_, _AUTHOR_ and _SECTION_.
"headerTemplate": null,
//Footer HTML template. Available variables: _PAGENUM_, _TITLE_, _AUTHOR_ and _SECTION_.
"footerTemplate": null
}
}

🐰 参考リンク

📚 おすすめの書籍

🖥 サーバについて

このブログでは「Cloud Garage」さんのDev Assist Program(開発者向けインスタンス無償提供制度)でお借りしたサーバで技術検証しています。 Dev Assist Programは、開発者や開発コミュニティ、スタートアップ企業の方が1GBメモリのインスタンス3台を1年間無料で借りれる心強い制度です!(有償でも1,480円/月と格安)