※この記事の内容にセクションを少し加えたページをサンプルとして公開してある→bookdown_test
はじめに
とりあえず細かいセッティングは抜きにして手元のRmdファイルをGitHub上に公開したい、という気持ちだったので最低限の手順をまとめた。
bookdownとは
R Markdownからドキュメントを作成するパッケージで、通常のR Markdownに対して(というかPandoc Markdownに対して)長編のドキュメントを生成するのに便利な機能が付け加えられている。図表や数式へのナンバリング、相互参照、複数ページのHTML出力などなど。
必ずしも本を書かなくてもいいし、R Markdownじゃなくて普通のMarkdownでも扱えるので、Rのコードを全く含まないポエムを書いたって全く構わない！
事前準備
-
bookdownパッケージをインストールしていなければインストールしておく。
install.packages("bookdown")
- githubで新規リポジトリを作成する。
- RStudioから
New Project -> VersionControl -> Gitと選択し、Repository URLに先程作成したリポジトリのURLを指定、新規プロジェクトを作成する。
Rmdファイルについて
- デフォルトではプロジェクトのトップディレクトリに配置されたRmdファイルが結合されたのち、Knitされる。
- 全てのRmdファイルが1つのRmdファイルとして評価されるので、例えば設定用のコードチャンクは先頭のファイルに1回書いてあればよい。
- チャンクラベルが重複しないように注意する必要がある。
- デフォルトではRmdファイルの結合順序は名前順である。
- ファイル名の先頭に数字を入れると良い。例えば
01_first.Rmdの次は02_second.Rmdといった具合に。 - ただし、
index.Rmdというファイルがあれば、常に最初のファイルとして使用される。 - アンダースコア
_から始まるファイルは無視される。
- ファイル名の先頭に数字を入れると良い。例えば
注: 上記の挙動は当然変更できるが、ここでは説明しない。
YAMLフィールドの指定
各種の設定は最初のRmdファイル(前述の通り、通常はindex.Rmd)のヘッダーにYAMLフロントマターとして記述する。以下に最低限の記述を示す。
---
site: bookdown::bookdown_site
output:
bookdown::gitbook: default
---
-
site: bookdown::bookdown_siteはbookdown::render_book()を呼び出すために必要な設定らしい。 -
outputフィールドで出力形式を指定する。 -
siteフィールド以外は別途_bookdown.ymlというファイルを用意して、そこに記述することもできる。 - 一部のbookdownに関連した設定は
_bookdown.ymlからしか読み込まれないので記述しなければならない。GitHubで公開しようとすると出力先ディレクトリを指定する必要があるので、実質_bookdown.ymlは必須である。 -
_bookdown.ymlのoutput_dirで出力先ディレクトリを指定する。GitHubでサイトとして公開するためにはdocs/以下に出力する必要があるので、最低限以下の設定が必要となる。このとき、---は不要である。なお、行末に改行が無いと怒られる(ビルドはできる)。
_bookdown.yml
output_dir: docs
outputフィールドの内容は時に長くなるのと使いまわしたくなるので、別途_output.ymlというファイルに記述しても良い。このとき前後の---が不要なのに加えて、output:も省略して下のフィールドから書き始める。例えば先程のフロントマターの内容を_output.ymlに記述するなら次のようになる。
_output.yml
bookdown::gitbook: default
ビルド
- BuildタブのBuild Bookをクリック。
- Buildタブが無い場合はファイルを保存してRStudioを開き直すと出る。多分。
公開
- GitタブからCommitしてPush
- GitHubのリポジトリページを開き、Settingsタブの下の方のGitHub PagesのSourceをmaster branch /docs folderに変更してSave
- 今設定したGitHub Pagesの欄に"Your site is published at ..."と説明が出ているので、そこからリンク先へ飛ぶとdocsフォルダ以下の内容が公開されている。
- Save直後は404が表示される。反映まで10分くらいかかることがある。