R MarkdownによるWebサイト作成 チュートリアル

以下の内容については,以下のページに出力しましたのでそちらを参照してください:

https://kazutan.github.io/RmdSite_tuto/

このリポジトリの使い方

「00_sample」から「04_sample」までのディレクトリ内に，それぞれ**_sample.Rprojというプロジェクトファイルがあります。説明資料で指示があったら，そのフォルダのプロジェクトファイルを開いてください。

レッスン0 専用のプロジェクトを準備

1. プロジェクトを新規で準備
2. 準備したら，**Tools - Project Option...**を開く
   (もしくは*.RprojファイルをRStudio上で開く)
   1. Build Toolsに進み，Websiteを選択
   2. サイトのルートディレクトリを設定
      (ここではプロジェクトのルートディレクトリにします)
3. OKをクリック

レッスン1 最小構成で準備してbuild

以下，01_sampleディレクトリを使います。該当ディレクトリ内のプロジェクトファイルを開いてください。

1. index.Rmdを準備
   • トップページ(index.html)用
   • ファイル冒頭のYAMLフロントマターにはtitleだけでOK
2. _site.ymlを準備
   • これがサイト全体設定ファイルとなります
   • ひとまず最低限のを記述しています
3. その他のページ用Rmdを準備
   • ファイル名などは適当に
   • 今回は簡単なのをひとつだけ
4. プロジェクトをBuild
   • BuildタブにあるBuild Websiteをクリック
     • もし見当たらない場合は，一度プロジェクトを開き直してください
   • 問題がなければ，(デフォで)_siteというディレクトリが作成
     • もしRmd内のチャンクにエラーがあって実行できない場合，buildもストップします
     • この中にWebサイトに必要なものが自動的に生成されています
     • 特に設定を変更してなければ，Viewerに表示されます
5. 生成物をチェック
   • 生成された_site/index.htmlをブラウザで開き，チェック

レッスン2 基本的なサイト設定

以下，02_sampleディレクトリを使います。該当ディレクトリ内のプロジェクトファイルを開いてください。

サイトの全体設定は_site.ymlファイルに記述していきます。以下このファイルの内容を説明していきます。

サイト名

name: "サイトタイトル"

• サイトのタイトルを文字列で指定します
• このサイトを開いた時，ウィンドウの一番上やタブに表示されます

navbar関連

navbar: 
  title: "My ウェブサイト"
  left:
    - text: "ホーム"
      href: index.html
    - text: "趣味"
      href: shumi.html

• navbar:以降ぶら下がるのがいわゆるメニューバー設定
  • title:はサイト名として常に表示される
  • left:以降ぶら下がっているのが項目で，左揃えで配置される
    • - とその下にぶら下がるのが1項目分の情報
      • -text:は表示文字列，href:がリンク先
• この他，色々設定できますが省略します
  • 詳しくは公式ドキュメントのここにほぼすべて書いてあります

output関連

output:
  html_document:
    theme: cosmo
    highlight: textmate
    toc: true
    toc_float:
      collapse: false
    df_print: "kable"
    include:
      after_body: footer.html
    css: site_style.css

• 通常のR Markdownでのoutputの指定と同様です
  • 設定可能項目はたくさん
  • (現時点での)最新一覧は以下の資料を
    R Markdownのhtml_documentで指定できるyamlヘッダ項目について - Qiita
• この設定が(原則)全てのRmdファイルに当たります
  • 個別のRmdファイルに記述すれば，そっちが優先されて上書きされます

output_dir

output_dir: "docs"

• buildで生成される，Webサイトに必要なファイル一式を出力する場所を指定
  • ここにできたものをまるっとWebサーバーに設置すればOK
  • 標準では_siteディレクトリ
  • github.ioに設置を考えているなら，docsがおすすめ

レッスン03 サイトデザインを考える

以下，03_exampleディレクトリを使用します。該当ディレクトリ内のプロジェクトファイルを開いてください。

開いたら，一旦buildしてみて確認してください。

知っておくべきこと

R Markdownでhtmlを生成してデザインを考える上で，以下のことは頭に留めておいてください:

1. RmdはPandocを利用してhtmlを生成
   • Rmd -> (knit) -> md -> (Pandoc) -> html
   • 良くも悪くもPandocの影響を色濃く受ける
     • Pandoc ユーザーズガイド 日本語版 - Japanese Pandoc User's Association
     • RStudioの"knit HTML"でPandocに送っている内容 - Qiita
2. 生成されたhtmlには**BootstrapとjQuery**が標準で組み込まれる
   • Bootstrapベースでデザインすると楽
   • 別のcssフレームワークにする場合は以下の記事を参照
     • R Markdownで標準のCSSとhighlightを取り除くには - Qiita

Rmdで生成されるタグのid, class

• 基本的にPandocの仕様で生成されます
  • Rmdのサンプルは03_example/id_class_check.Rmd
  • 生成されるhtmlは03_example/docs/id_class_check.html
  • これの詳しい解説は，以下の記事を参照
    • R Markdownで生成するhtmlタグ要素のidとclassを確認 - Qiita
• 上記サンプルを参考に，cssを設定すればOK
  • サイト全体テーマなら，_site.ymlで指定したcssファイルに
  • 個別ページで当てたい場合については後述

Bootstrapのgrid systemを利用

Bootstrapはgrid systemを採用しています。R MarkdownではBootstrapを標準で組み込んでいますので比較的簡単に実装できます。

実装する方法はいくつかあります:

1. <div>タグ直打ちで準備
   • gridレイアウトにしたい部分に対して
     を直打ちして指定
   • 生成物が複雑になりがちでメンテしにくくなる
2. Pandocの拡張機能を利用してclass属性を付与
   • 詳しくは以下の記事を参照
     • R MarkdownでBootstrapのグリッドシステムを利用する - Qiita
   • Rmdのサンプルは03_example/grid_test.Rmd
   • 生成されるhtmlは03_example/docs/grid_test.html
   • 設定する見出しのレベルにさえ配慮しておけば簡単

個人的には後者をおすすめします

cssの優先順位

• 個別ページでcssを設定した場合_site.ymlで指定したcssと差し替える
  • サイト設定によるcssを活かしたい場合:
    • cssファイルを2つ(orそれ以上)全てそのページで指定
    • yaml部分でincludeを活用してスタイルシートを指定
    • cssチャンクを利用して部分にstyleを記述
• cssチャンク > includeによる指定 > サイト設定 の順で優先される
  • Rmdサンプルは03_example/css_test.Rmd
  • 生成されるhtmlは03_example/docs/grid_test.html

他の複数ページでも同じスタイルを利用するのであれば，yamlのincludeオプションでうまく当てるのがスムーズです。もし「このページだけでちょっと当てたい」というのであればcssチャンクを使うのが楽でしょう。

レッスン04 発展編

以下，04_exampleディレクトリを使用します。該当ディレクトリ内のプロジェクトファイルを開いてください。

開いたら，一旦buildしてみて確認してください。

Rでhtml生成

• Rでhtmlを生成していくことも可能
  • knitr::kableなどもそのひとつ
  • htmltoolsパッケージを駆使すれば色々できる
  • 詳しくは公式ドキュメントのこちらを参照
• たとえばサムネイルを作成することも可能
  • Rmdサンプルは04_example/html_gene.Rmd
  • 生成されるhtmlは03_example/docs/html_gene.html

JavaScriptを利用

• htmlwidgets系を使えばインタラクティブな可視化
  • 詳細は省略しますが，そのままRチャンクに組み込めばOK
• R MarkdownではJavaScritpチャンクも使用可能
  • 詳しくは公式ドキュメントのこちらを参照
  • jQueryを標準で読み込んでいるので，そのまま使える
• htmlwidgetsやjQueryを組み込んだ例:
  • Rmdサンプルは04_example/js_test.Rmd
  • 生成されるhtmlは03_example/docs/js_test.html

その他

説明および具体例は省略します。

• includeオプションとexcludeオプションでoutput_dirへファイルをコピーするかどうかを制御可能
  • 詳しくは公式ドキュメントのこちらを参照
• ナビゲーションバー(navbar)について,自分でもっとBootstrapの機能を使ったものにできます
  • _navbar.htmlというファイルを準備
  • ここにBootstrapのnavbarに関するhtmlシンタックスを記述すればOK
  • 詳しくは公式ドキュメントのこのあたりを参照
• 繰り返し使うような要素はそこを別Rmdファイルに部分化し,呼び出して使うと楽
  • 詳しくは公式ドキュメントのこのあたりや,この記事あたりを参考にしてください

サイト公開(デプロイ)

サイトを作成したら公開するのですが，設置する場所が必要です。

通常のWebサーバー

• 設置先のサーバーを準備
• サーバ上の，Webサイトでのルートディレクトリに設定した場所を確認
• _site.ymlでoutput_dir: 指定した出力先(標準では_site/)に入っているファイルやディレクトリをまるっとコピー

ようするに，出力されたものをまるっと置いてしまえばOKです。

GitHub上に設置して公開

• GitHubにリポジトリを作成
  • 公開するにはPublicである必要あり
• プロジェクトのディレクトリをGitHubリポジトリに紐付け
  • .gitignoreにdoc/を追記しとくこと
• _site.ymlのoutput_dir: を**"docs"**へ指定
  • 設定したらbuildを実行
• commitしてmasterにPush
• ブラウザでGitHubの該当リポジトリへ
  • Settingタブをクリック
  • 下へスクロールしてGitHub Pagesへ
  • Sourceで，Master branch /docs folderに切り替える
• しばらく待って，https://(アカウント名).github.io/(リポジトリ名)/へアクセス

以降は修正したらbuildしてcommit - pushでOKです。Gitに慣れているならば，これが一番楽になるでしょう。また，上記のレッスン00でプロジェクトを準備する際に，はじめからVersion Controlを指定しておくと楽でしょう。

Enjoy!