最近まわりで何かとblogdownパッケージが話題です。このブログもblogdownで作成していますし,紹介する記事も増えてきました。

そこで自分の中で検証して,現時点でわかったことをTipsとしてまとめてみようと思います。また新たにわかったことは別記事にでも書こうかと思います。

blogdown入門

blogdownとは

blogdownはRを使ってblogのような静的Webサイトを生成するためのパッケージです。サイト生成にはHugoというサイト生成アプリケーションを利用しており,これはGo言語で書かれています。

Hugoについて

このHugoの特徴としては生成処理が早く,またモダンなデザインのテンプレートがいろいろあって,すぐに実用的なものが作成可能というのがあります。

またHugoの重要なポイントとして,公式ドキュメントが非常に充実していることが挙げられます。blogdownでやりたいことや行き詰まることが出たら,Hugoの公式サイトを参照するのをおすすめします:

blogdownのスタートアップ

blogdownがどういうものか,そして導入の方法については,すでにいい記事がありますので,以下を参照してください:

Tips

上記の記事に記載されていなくて,自分の中でメモしときたい内容をいくつか。

blogdownの仕組みについて

ちょっと込み入った内容です。

blogdownの実体

blogdownは,正直ほとんどHugoのR向けWrapperです。

例えばサイトを作成するnew_site()は,初期値を確認・設定した上で,それらをhugo_cmd()に送っています。また,new_content()もhugoへ新しいコンテツを作成するためのコマンドを送っています。そしてサイトを生成するbuild_site()は設定などを整理・確認してbuild_rmds()へ送り,Rmdを処理したうえでhugo_build()でbuildしています。このbuild_site()のコードおよびそこからの流れはblogdownの中身を把握する上でポイントとなるので,余力があるならぜひ覗いてみてください。

Rmd or md?

blogdownでbuildすると,content内にあるRmdやmdがレンダリングされて,自動的に最適な形で出力先へ出てくるようになります。つまりはblog記事はmdでもRmdでもどちらでも可能でhtmlが生成されます。ただし,この時用いられるレンダリングエンジンがRmdとmdで異なります。詳しくはblogdownのドキュメントのここを参照してください。

Rmdの場合,通常のR Markdownと同様でknit - Pandocという処理を行います。この時ベースになるoutputはblogdown::html_page()で,これはbookdown::html_document2()でいくつかの設定をblog(hugo)向けに絞ったものとなっています。なのでいつものR Markdownのoutputオプションを指定したい場合,以下のように指定すればOKです:

---
title: R Markdownでの諸々のテスト
author: kazutan
date: '2017-03-22'
slug: rmd-test
categories:
  - R
  - R Markdown
tags:
  - R
  - R Markdown
archives:
  - "2017"
  - "2017/03"
output:
  blogdown::html_page:
    toc: true
---

これはこのブログのこの記事のyamlフロントマターで当てている内容です。このような設定は,Rmdで記事を作成した場合に有効です。

なお,Rmdで作成するとHugoがmdレンダリングで使用するBlackflidayの機能などが使えないという制約がつきます。なのでよくHugo関連のドキュメントで書いてあるような拡張機能が使えない場合があるので注意してください。

一方mdの場合,Hugoがmdをレンダリングします。HugoはBlackflidayを利用してレンダリングしています。またHugoが提供している拡張機能もそのままドキュメントに盛り込めます。例えば,HUGOMORE42は手動で「続きを読む」みたいな区切りを設定するものですが,mdファイルであればこれを差し込むことで実装できます。ただし,Rmdファイルで記事を書いた場合には機能しません。

では「Rmdとmdのどっちがいいの?」と聞かれそうですが,ケースバイケースと言わざるを得ません。Rチャンクなどを埋め込みたいのであればRmd一択になるでしょうし,Blackfridayなどを利用したいのであれば,mdも選択肢になる,と言った感じでしょうか。まだ私がそこまでBlackfridayなどに明るくないのでRmdにより多くのメリットを感じていますが,そのうち機会があれば調べてみたいとは思ってます。

コメント機能の実装

Hugoは静的なサイトなので,CMSで標準で実装されているコメント機能などは難しくなります。ここはシンプルに外部サービスを利用するのが楽だと思います。

このブログではdisqusという外部サービスを利用しています。詳しくはdisque 使い方とかでググってもらえれば,アカウント登録のやり方など解説している記事がヒットするでしょう。有償版もありますが,無償版でも使えます。

blogdown(というかhugo)では割と簡単に組み込むことができます。Hugo公式ドキュメントのこちらを参照してください。多分大抵のテーマでさくっといけるはずです。

出力先ディレクトリの設定など

blogdown(というかHugo)のデフォルトはpublic/となっています。通常のWebサーバに設置したいのであれば,単にこの中身をまるっと設置すればOKなのですが,github.ioを利用するとなると面倒です。

最初の方に紹介した2つの記事では「public/の中身をdocsにコピーしてpush」とありますが,これも手間です。もうちょっと簡単にやる方法がHugo公式ドキュメントのこちらに記載してありますので参照してください。

なお,単に出力先をdocs/に変更したいだけなら,config.tomlに以下の一行を追加してください:

publishDir = "docs"

またgh-pagesブランチで運用したいなら,先ほど紹介したリンク先に詳細手順が紹介してあります。多少gitの知識が入りますが,丁寧な解説なのでそれほど苦しくはないと思います。

Hugoでcjk対応

英語オンリーなブログであれば不要なのですが,日本語ベースでblogdown(Hugo)を利用するならcjk対応をさせておくほうがいいでしょう(cjkは中国語©,日本語(j),韓国語(k)のこと)。これを設定しておかないと,トップページなどで記事一覧を出した時,記事の要約が自動でうまく処理してくれずに面倒なこととなります。

設定方法は,config.tomlに以下の一文を記述してください:

hasCJKLanguage = true

その他の全体設定について

Hugoではいわゆるブログ全体設定というものがかなりたくさんありますし,拡張機能もたくさん準備してあります。詳しくは公式ドキュメントをざっと見てみてください。

ただし,Hugoはテーマテンプレートによって設定項目がかなり変わってくるのを注意してください。正直これがかなり面倒で,必ず設定したテーマのドキュメントをよく読んでください。このブログで設定しているテーマはTranquilpeakで,多機能でいろいろカスタマイズ可能ということで選びました。

新規PostはRStudio Addinで

最近のblogdownなら,新規Postを準備するためのRStudio Addinが準備されています。RStudioのAddin…ボタンから,New Postを選択してください:

このようなダイアログボックスが出てきます。基本的に必要な事項はここで設定できます。設定したら右下のOKをクリックすれば,新規Post用のファイルが自動的に適切な場所に生成されます。

なおCategoriesやtagsもここで設定できますし,これらですでに使ったことがあるものであればクリックで選択して入力していくことが可能ですし,新規で作ることも可能です。いちいち他のところで設定しなくても後でBuildした時にHugoが自動的に対応してくれます。便利です。

下書き(draft)

上記のようにRStudioのAddinで作成した場合,yamlフロントマターにdraft: yesというのが自動で組み込まれているかと思います。これはまさにdraft機能で,yesなので下書きモードとなっています。

下書きモードがONになっていると,build_site()を実行してもその記事はサイトには組み込まれない(publicには入ってこない)ようになります。私の場合,記事を書きながらknitを実行して表示を確認し,書き終えたらdraft: falseに書き換えてserve_site()で確認するようにしています。

また,記事を書いていく時に「ちょっと今さくっとどんな感じになるか確認したいな」と思ったら,knitを実行してください。テーマなどは当たりませんが,チャンクが実行されてhtmlが生成され,確認することができます。毎度毎度buildしたりしなくていいので楽ちんですよ。

build_site()とserve_site()について

serve_site()を実行するとbuildされ,RStudioのViewerペインに表示されます。実際何をしているかといういと,まずbuild_site(TRUE)を実行し,servr::httw()にてローカルサーバーを立てて表示させています。つまり,serve_site()を実行するとLocal用にbuildして,それをローカルで表示させているを実行しています。

blog設定や内容にもよりますが,serve_site()はあくまでローカルでの表示用にbuildしていますので,そのまま公開するとうまく表示されない場合があります。このようなことがあるので,公開用に設置する前に一度build_site()を実行する手順を加えておくことをおすすめします。

参考資料

  • blogdown: Creating Websites with R Markdown
    • blogdown公式ドキュメント
    • でも全然整備されていない…つらい
  • Hugo - Introduction to Hugo
    • Hugoの公式ドキュメント
    • 非常に充実
    • Getting Started, Content, Themesのところはぜひ読んでください
    • いろいろやりたくなったら,Template, Taxonomies, Extrasに手を出してください

その他わからないところや詰まったところがあったらr-wakalangの#rmarkdownチャンネルなどで質問するといいかも。

またいろいろTipsみつけたら続編を書くかもしれません。

Enjoy!