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の設定

• (1) GitHubでリポジトリを作成
• (2) ブランチ gh-pages にhtmlをpush
• (3) カスタムドメインを設定 => Using a custom domain with GitHub Pages - User Documentation

🎳 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も簡単に利用できそうです。

• GitBook/GitHub/CircleCIでメンテ可能な仕様書を書く - Qiita
• Jenkins + GitBook で GitHub のドキュメント(PDF)のパブリッシュを自動化しよう - Qiita
• S3+CloudFront+ACM(AWS Certificate Manager)でHTTPS静的サイトを作ってみた - Qiita
• S3+CloudFrontだけでリダイレクト設定を作る - Qiita

🗻 (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
    }
}

• book.json | GitBook 简明教程

🚕 参考リンク

• UTF-8-MACをUTF-8に変換する - Qiita
• GitBookをGitHub Pagesで公開する ヘ(^o^)ノ - Murajun’s Style
• gitbookで技術書を書く環境の構築手順 | takemikami’s note
• GitBook/GitHub/CircleCIでメンテ可能な仕様書を書く - Qiita
• GitBook 環境を準備してみる ｜ Developers.IO
• S3を使った静的サイト構築… - Qiita
• npmのpackage.jsonを最新のバージョンに更新する

🖥 VULTRおすすめ

「VULTR」はVPSサーバのサービスです。日本にリージョンがあり、最安は512MBで2.5ドル/月($0.004/時間)で借りることができます。4GBメモリでも月20ドルです。 最近はVULTRのヘビーユーザーになので、「ここ」から会員登録してもらえるとサービス開発が捗ります！

📚 おすすめの書籍