R Markdown + Githubでモダンな個人Webサイト構築

Hijiyama.R #6

kazutan

はじめに

目指すもの

  • rmarkdownで静的なWebサイト構築
  • それをgit & githubで運用
  • github.ioとして公開

Webサーバーも含め，無料でサイトを構築&公開しよう

本発表の流れ

  1. 全体的なコンセプト
  2. GitHubリポジトリの準備
  3. サイトの中身を作成
  4. GitHubリポジトリへpush
  5. 公開のための設定

必要なもの

  • gitの知識
    • 出来る限りコマンドを使わないように説明します
  • githubの知識，アカウント
    • 出来る限りシンプルに説明します
  • rmarkdownの知識
    • 最小構成で説明します
  • webの知識
    • html & cssに触れたことある程度でOKです

全体的なコンセプト

R Markdownで静的サイトを作ろう

  • R Markdownを使えばhtmlドキュメントが作れる
    • Bootstrapが組み込まれている
      • シンプルで簡単にそれっぽいのが作れる
  • R Markdownにはrender_site()関数も
    • つまりWebサイトを一気に作ることも想定
    • 一度作ってしまえば，あとは簡単

Github Pages利用しよう

  • Webサーバを準備する必要
    • レンタルすると有料
    • サーバメンテが面倒
  • GitHub Pagesなら3ステップでOK
    • リポジトリを準備
    • Fileをアップロード(push)
    • 公開用にセッティング

構築の流れ

  1. GitHub上で公開用リポジトリを準備
  2. そのリポジトリからRStudioでProjectを作成
  3. Webサイト用にProjectの設定を変更
  4. yamlファイル，Rmdファイル等を作成
  5. Build Websiteを実行
  6. GitHubへpush
  7. GitHub側で公開向けに設定

メリット

  • Rがそのまま使える
  • 統一感のあるデザインが組みやすい
  • 構築から公開まで無料で可能
  • Markdown記法でドキュメントを作れる
  • gitによるバージョン管理が可能
  • Pull Requestによる共同編集が可能
  • やろうと思えばとことん作り込める
    などなど

リポジトリとプロジェクトの準備

ローカルマシン等の準備

  • R/RStudio側の準備
    • RStudioはv1.0以上を推奨
    • rmarkdownとknitrは最新版へ
    • あとはRmdファイル内で使うパッケージを入れておく
  • git環境を準備
    • マシンにgitをインストール
    • gitにユーザー名など基本設定をしておく
    • sshキーを作成してGitHubにも登録しておく
    • 詳細は省略

新規でリポジトリを準備

  1. ブラウザでGitHubにログイン
  2. 新たにリポジトリを作成
    • 個人サイトなら(アカウント名).github.ioというリポジトリ名で
      • これで作るとhttps://(アカウト名).github.io/というurlで作れるため
    • そうでないなら適当なリポジトリ名で
      • これで作るとhttps://(アカウント名).github.io/(リポジトリ名)というurlでサイトができます

SSH用のアドレスをコピー

  1. できたGitHubリポジトリの右上の方にある緑のClone or downloadをクリック
  2. Clone with SSHになっているのを確認
    • おそらくgit@github.com:(アカウント名)/(リポジトリ名).gitとなっているはず
    • もしHTTPSになってたらUse SSHをクリックして切り替え
  3. クリップボードアイコンをクリックしてアドレスをコピー

RStudioでプロジェクト準備

  1. RStudioを起動
  2. New Project…を選択
  3. Version Controlを選択
  4. Gitを選択
  5. Repository URL:に，さっきコピーしたのを貼り付ける
  6. ディレクトリの場所を確認し，Create Projectをクリック

Build設定

  1. メニューのTools - Project Options…をクリック
  2. Build Toolsパネルを編集
    1. Project build tools:をWebsiteへ
    2. Site directory:を，プロジェクトのホームディレクトリへ
  3. OKをクリック
  4. RStudioを再起動
    • もしくはプロジェクトを一旦閉じてまた開く
    • 必須ではないけどしておいたほうが無難

サイトの中身を作成

基本的な流れ

  • Rmdファイルを準備
    • index.Rmdを作成(トップページ)
    • その他のページをRmdで準備
  • サイト設定用ファイル(_site.yml)を作る
    • これがポイント
    • 今回は最低限の部分だけ

詳しくは以下を参照してください:

Rmdファイルを準備

  • いつものRmdとほぼ同様
  • ただし，yamlフロントマターはtitle:のみでOK
  • index.Rmdはトップページ用に準備
  • それ以外のRmdのファイル名はお好みで
    • もしページにまとまりがあるなら，それを意識して命名すると楽
    • hoge_fuga.Rmd, hoge_piyo.Rmdみたいに
    • あるいは01-hoge.Rmd, 02-fuga.Rmdなど
  • カテゴリ別にディレクトリに分けるのは非推奨
    • Buildが面倒になるため

サイト設定ファイル(_site.yml)を準備

Kazutan.Rの_site.ymlから一部抜粋:

name: "Kazutan.R"
navbar:
  title: "Kazutan.R"
  left: 
    - text: "about"
      href: "about.html"
output:
  html_document:
    css: site_style.css
output_dir: "docs"

重要なのはoutput_dir: "docs"で，GitHubで公開するならこれを入れておくこと!

その他のファイルの準備

  • .nojikillというファイル(中身は空っぽ)をホームディレクトリ作っておく(ほぼ必須)
    • これを設置しておかないと微妙なことになるため
  • 必要ならば画像ファイルを準備(任意)
  • README.mdを準備(任意)
    • なくてもいいけどあったほうが望ましい
  • その他必要な素材を準備(任意)
    • 使用するcssファイルやjsライブラリなど

Build Website

  1. RStudioの右上のPaneにあるBuilsタブをクリック
  2. Build Websiteをクリック
    • Buildが実行され，Rmdらがレンダリング
    • knitでエラーがでると途中でストップ
      • エラーが出ないように修正して再度Build
  3. うまくいけばdocsディレクトリ内に出力
    • この中身をまるっと公開すればWebサイトができる!
    • GitHub以外へ公開するなら，これをftpなりでUploadすればOK

GitHubリポジトリへpush

Terminalで行う場合

かなり省略してます。

$ cd (プロジェクトのホームディレクトリへのパス)
$ git status
$ git add (各種ファイル)
  • git statusで状態を確認
  • git add (ファイルパス)でstagedにするファイルを指定
    • もし全てをあげたいならgit add -AでもOK
    • でもあんまりおすすめしない
$ git commit -m "コミットメッセージ"
$ git push
  • git commitでローカルのリポジトリに変更を登録
    • git commit -mで，その場でコミットメッセージを入れれる
    • もし-mが抜けると，コミット編集画面が出る
      • 本当はそっちの方がいい
      • でも慣れるまでor簡単な分ならこれでもいいかな
    • コミットはこまめに行うこと
  • git pushでリモート(ここではGithub)へ変更を反映
    • うまくいけば，これでGitHubのリポジトリに反映
    • remoteの設定はRStudioでプロジェクト作る際に自動的に設定されている

RStudioのUIで行う場合

  1. RStudioの右上のPaneにあるGitタブをクリック
  2. version管理するファイルに対し，Stagedのチェックを入れていく
  3. Commitボタンをクリック
  4. ファイルを確認し，Commit messageを入力
  5. Pushボタンをクリック

用語としては，先ほどのTerminalの場合で説明しているので省略します

公開のための設定と今後の更新作業

公開ディレクトリ(ブランチ)を指定

  1. GitHubの該当リポジトリへ
  2. リポジトリ名のすぐ下にあるタブ一覧からSettingをクリック
  3. 下へスクロールしGitHub Pagesへ
  4. Sourceのところを設定
    1. プルダウンメニューをnoneからmaster branch /docs folderに切り替える
    2. 横のSaveボタンをクリック

Webサイトの確認

  1. https://(アカウント名).github.io/(リポジトリ名)にアクセス
    • リポジトリ名が(アカウント名).github.ioの場合，
      https://(アカウント名).github.io/へアクセス
  2. 無事に表示できていたらOK
    • 404だった場合，少し時間を置いてアクセス
    • それでも出てこない場合はurlを再確認し，再読み込み

更新作業

  1. RStudioでRmdなどを編集
  2. Build Website
  3. GitHubへpush
    • add - commit - pushの流れ
    • 一度通っているので，あとは簡単です
  4. urlへアクセスして反映を確認

以上です。お疲れ様でした。

さいごに

留意事項

  • gitの基礎はおさえよう
    • 今回ほぼ省いています
    • gitの理念と基本的なコードは憶えておいた方がいい
    • 無理せず，一つずつコマンドを使っていきましょう
  • 文字コードに気をつけよう
    • 割と引っかかる
    • OSをクロスするとよく発生
  • 他のRmdサイトを参考にしよう
    • 特に_site.yml

Enjoy!