Gitbook を使って文書を公開する

2018/11/27,

Alfons Morales

Gitbook を使って文書を公開する

自作の小説の公開場所として、「小説家になろう」や「カクヨム」は作品公開の場所としては最適です。たくさんの人が日々アクセスしていますし、かなりの読者がいますから。

ですが、ちょっと公開するのが面倒くさい。

たいていの人は原稿を TXT ファイル、もしくは Word ファイルで書いていると思います。そして原稿を執筆してから、文書全部をカクヨムのサイトにコピー&ペーストして公開する。

推敲もほぼ完了して文書の内容を変更しないのであれば、一度アップロードだけで完了です。ですが、頻繁に書き換える場合、アップロードの手間は少しめんどくさい。

「同じ作業を何度も繰り返すのは極力避けてしまいたい。アップロードを自動化してしまいたい」という欲求があります。

文書は当然 Git で管理していることを前提とすると、Git Push した瞬間、閲覧可能なサイトが生成されるのが大変喜ばしい。

文書作成に特化した Gitbook というツールを使って文書の公開を自動化しましょう。今回は Gitlab-Pages を利用してサイト公開までを自動化します。

Gitbook とは

gitbook とは markdown で書かれた文書を美しい書籍に変換することが出来るコマンドラインツールです。gitbook を利用することで簡単に目次機能がついたウェブサイトを作成することができます。

デモ

どのように表示されるかはサンプルを用意したのでご覧ください

デモ

リポジトリの設定例

Gitlab での設定例を公開しています。

gitlab

Gitbook に対応したファイル構成

root/
  |- README.md : どのような文書かの説明
  |- SUMMARY.md : 目次
  |- .gitignore : git の無視設定
  |~ .gitlab-ci.yml : gitlab-ci の設定ファイル
  |- source/
      |- text1.md : 本文1
      |- text2.md : 本文2

README.md はどのような文書なのか説明するものにしましょう

# 本文書について
Gitbook の使い方について説明する。

SUMMARY.md の中身は以下のように書きます。

#Summary

* [この文書について](README.md)
* [本文1 タイトル](source/text1.md)
* [本文2 タイトル](source/text2.md)

本文テキストは各自でお好きに書いてください。

むかしむかしあるところに、おじいさんとおばあさんが……

.gitignore に不要なファイルを無視する設定を記述しておくとファイル管理が容易になるでしょう

/_book/
/node_modules/
/book.pdf
/book.mobi
/book.epub
/public

Gitlab-Pages を利用して Gitbook を公開する

さて、文書を作成したならば、いざファイルを公開していきましょう。

Gitlab に新規リポジトリを開設し、作成した文書を git push でアップロードしましょう。

ページの公開方法として Gitlab-Pages を利用します。Gitlab が無料で提供しているホストサービスです。

.gitlab-ci.yml という設定ファイルに従って、ウェブサイトを公開できます。

GitLab Pages examples (英文) : 設定方法についてはここのサイトを参考にしました。

.gitlab-ci.yml のファイル設定は次のとおりです。

# requiring the environment of NodeJS 10
image: node:10

# add 'node_modules' to cache for speeding up builds
cache:
  paths:
    - node_modules/ # Node modules and dependencies

before_script:
  - npm install gitbook-cli -g # install gitbook
  - gitbook fetch 3.2.3 # fetch final stable version
  - gitbook install # add any requested plugins in book.json

test:
  stage: test
  script:
    - gitbook build . public # build to public path
  only:
    - branches # this job will affect every branch except 'master'
  except:
    - master

# the 'pages' job will deploy and build your site to the 'public' path
pages:
  stage: deploy
  script:
    - gitbook build . public # build to public path
  artifacts:
    paths:
      - public
    # expire_in: 1 week
  only:
    - master # this job will affect only the 'master' branch

.gitlab-ci.yml が git リポジトリに存在すると自動的に CI ツールがビルドとページの公開を行なってくれます。

公開されたサイトURLは 設定 -> Pages から確認できます。