記事を書いたモチベ
R studioなどを使ってコードを実行しているとき、この内容をどこかにいい感じにまとめてほかの人に共有したいなーって思ったことありますよね？
Rmdファイルはhtmlやpdfに変換できますがそのファイルたちを共有する方法がなかなか難しいです。
webサイトとして公開できれば見やすい＆壊されないのではというところから始めました。
対象
- 複数の章(Rmdファイル)に分かれるようなナレッジを1つのサイトとして共有したい
- Rmdでの実行結果(tableやグラフ)もサイトに掲載したい
- mac/windowsユーザー
- R studioを使用可能
手法比較
早速ですが、この記事で紹介する3つの手法について下記にまとめます。
個人的にはquartoを使うのがおしゃれ、かつカスタマイズ性が高いです。
| 方法 | 利点 | 欠点 |
|---|---|---|
| bookdown bs4_book |
簡単に実装できる 見た目がきれい 情報量が少ない際に適する コードチャンクの設定を一括で指定できる |
階層構造が少ないため情報量が多いと見にくい header1が自動で別章になってしまう コードブロックを折り畳めない |
| quarto | 見た目がきれい サイドバーを階層構造にできるため情報量が増えても問題ない コードブロックを折り畳める アイコンも設定可能 |
.Rmd→.qmdに変更する必要あり |
※あくまでもデフォルトの設定での比較となります
※github pagesにアップロードした時の挙動を比較しています
bookdown
見た目
- シンプルでpaper likeなので見やすい
- sidebarはこれ以上階層を増やせないので章が多すぎると見にくくなってしまうことも
準備
bookdownというライブラリをインストールして、一度R studioを再起動してください。
以下のようにBuildというタブが追加されていればOKです
作成方法
- R studioでNew Project＞New directory＞Book project using bookdown
- 任意のフォルダに新規プロジェクトを作成する
上記の手順で作成すると自動的にRmdファイルや設定のために必要なファイル(_bookdown.ymlなど）が生成されます。
画像付きの詳細はこちら
設定
delete_merged_file: true
language:
ui:
chapter_name: "Chapter "
output_dir: docs #github pagesを使う上では必須
- delete_merged_file
- trueにしておくことで、レンダリング時に自動で上書きされます
- chapter_name
- 設定すると各Rmdファイルのheader1レベルのタイトルに自動で、その名前と通し番号が割り振られます
- output_dir
- 出力先のディレクトリを指定します（デフォルトは_bookフォルダ）
- github pagesではdocs配下のhtmlファイルを元にwebページを生成するため必須の設定です
bookdown::gitbook:
css: style.css
config:
toc:
before: |
<li><a href="./">A Minimal Book Example</a></li>
after: |
<li><a href="https://github.com/rstudio/bookdown" target="blank">Published with bookdown</a></li>
edit: https://github.com/USERNAME/REPO/edit/BRANCH/%s
download: ["pdf", "epub"]
- beforeのところに記載した名前がタイトルになります
- デフォルトでは
bookdown:pdf_bookの設定項目がありますが、webサイト構築には必要ないので削除or放置でOK
Build（Rmd→html）
以下のBuildボタンを押下する
docsフォルダの中に自動でhtmlファイルなどが生成される
TIPS
Rmdファイルを1フォルダ内にまとめたい
初期設定では、.Rprojと同じ場所に.Rmdファイルが生成されており、少しゴチャついて見える。
-
booksというフォルダに以下のファイルを移動させる
-
_bookdown.ymlのoutput_dirを
../docsに変更する -
Build時にBuildボタンではなく以下のコマンドをR consoleで実行する
rmarkdown::render_site(encoding = 'UTF-8', input = "books/")
Github Pagesでの公開方法
- settingsのpagesに移動する
- branchをmainに設定し、/docs配下のデータをサイトに表示するよう設定する
bs4_book
見た目
- 目次が左右に分割されている
- bookdownのオプションの一つであるためそれほどbookdownと機能は変わらない
作成方法
- bookdownとほぼ同様
- html book formatをbs4_bookにするだけ
設定
特筆すべきことは特にありません。
詳細は以下をご覧ください。
Quarto
見た目
- 上部のバーやサイドバーを自由に設定できます
- サイドバーではネストの深さを自由に設定できるので情報量が多いページに適しています
- ロゴ画像も挿入可能
- コードが折りたためます
事前準備
詳細は下記の公式サイトをご覧ください
各種プラットホームで使用できるCLIツールが用意されています。
作成方法
R studioでNew Project>New directory> Quarto Website
設定
project:
type: website
output-dir: docs #github pagesで必須
website:
title: "quarto" #サイト名入れる
site-url: "" #トップページのURLを入れる
page-navigation: true
page-footer: #フッターの設定
right: ""
left:
- icon: github
href: "" #githubのリポジトリURLなどを入れる
- icon: globe
href: "" #公開しているサイトのURLなどを入れる
background: "#AAB1B3"
navbar: #上のバーに記載する内容の設定
left:
- href: index.qmd
text: Home
- about.qmd
sidebar: #サイドバーに記載する内容の設定
logo: "image/logo.png" #ロゴを設定可能
pinned: true
align: center
style: "docked"
search: true
collapse-level: 1
contents: #サイドバーのコンテンツ
- text: "Home"
file: index.qmd
- text: "Contributors"
file: contributors.qmd
- section: "R" #ネストできる
contents:
- book/R/1.Create_DataSet.qmd
format:
html:
page-layout: article
theme: zephyr #cosmo #sketchy #quartz #morph #lumen #sandstone #zephyr
css: styles.css
code_folding: hide #hide #true #false
toc: true
grid:
sidebar-width: 250px
body-width: 900px
margin-width: 300px
editor: visual
- 上記は好みによるので必要な部分だけ設定してみてください
Render(Qmd→html）
- terminalで
quarto preview- プレビュー状態のWebサイトが自動で立ち上がります
- qmdファイルなどを編集して保存すると自動で再レンダリングされて反映されます
- terminalで
quarot render- GitHub公開用にhtmlファイルを生成します
TIPS
コード折り畳み関連
その他Quartoに特有のTIPS