パッケージ紹介ページを作成したかった
最近Rパッケージを作り、せっかくだからpkgdownのページを作ってみたいなと思ってちょっと試した結果をメモしておきます。
パッケージを作るときの（追加）作業
RStudioのプロジェクト機能を使用して、GitHubと連携してパッケージを作成済みであることを想定します。
happygitwithr.com
Reference manualのファイル（Rdファイル）はroxygen2の機能を使用して作成しておきます（Rのソースファイルにコメントとしてreference manualファイルの生成に必要な内容を所定のタグを使って定義する）。
roxygen2.r-lib.org
pkgdownにはreference manualファイルの内容を見栄えの良いページに変換してくれるので、とてもありがたいです。
pkgdownでは 色々できる ようです（他の機能も試して、感想などをまとめたいところです）。
pkgdown.r-lib.org
とりあえずreference manualファイルとindex.mdまたはREADME.mdがあればpkgdownでページを作成できるようだったので、README.mdも書いておきます。
rmarkdown.rstudio.com
pkgdownの設定と実行
以下のページに作業手順が書いてあります。
pkgdown.r-lib.org
RStudioでパッケージのプロジェクト内で、初回のみ以下を実行するようです。
# Run this once to publish your site regularly usethis::use_pkgdown_github_pages() # Run once # Remove docs/ from gitignore to ensure it is checked into git. usethis::use_pkgdown()
以下と全く同じエラーが出たので、git remote add origin [URL] をしておきました。
forum.posit.co
Reference manualファイルやコンテンツをアップデートしたときは、以下で再生成できます。
# Run everytime you want to update your site pkgdown::build_site()
生成したHTMLファイル等はパッケージディレクトリの /docs に格納されます。
デフォルト設定では .gitignore に /docs が追記され、gh-pages というbranchが作られます。
GitHub Pagesでは gh-pages という名前のbranchをドキュメント公開元にする仕様だったそうですが、今はオプションから別のbranchを使う設定ができるようになっています。
切り替えがやや面倒くさいので、自分はmaster branch（以下ではmainという名前のbranch）から公開する設定を試しました。
.gitignore から /docs を消し、生成された /docs のファイルは適当なタイミングでcommitしてpushしておきます。
GitHub Pagesの設定
パッケージを載せているrepositoryのPagesの設定を行います。
Settingsから
Pagesを開き
SourceとBranchの所を適切に設定します。
gh-pages のbranchを使う場合は、↑の画像とは異なる設定にする必要があります（これは main という名前のbranchから公開する設定です）。
ページ公開ができていればチェックマークがつくようです。
今回はGitHub Pagesの機能を使ってトップページも一緒に作りました。
nshi-stat.github.io
数式を使用したい場合
公式ページには_pkgdown.ymlのtemplateの所にmath-rendering: katexを追記して、pkgdown::build_site()を再実行するとKaTeXを使用して数式をレンダリングしてくれると書いてありました。
template: bootstrap: 5 math-rendering: katex
しかし、私の環境ではこれは動作せず、以下のようにCDNから読み込むように直接書く必要がありました（将来的には修正されるかもしれません）。
template:
bootstrap: 5
includes:
in_header: |
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css" integrity="sha384-zh0CIslj+VczCZtlzBcjt5ppRcsAmDnRem7ESsYwWwg3m/OaJ2l4x7YBZl9Kxxib" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.js" integrity="sha384-Rma6DA2IPUwhNxmrB/7S3Tno0YY7sFu9WSYMCuulLhIqYSGZ2gKCJWIqhBWqMQfh" crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/contrib/auto-render.min.js" integrity="sha384-hCXGrW6PitJEwbkoStFjeJxv+fSOOQKOPbJxSfM6G5sWZjAyWhXiTIIAmQqnlLlh" crossorigin="anonymous" onload="renderMathInElement(document.body);"></script>KaTeXのCDNを読み込むコードはバージョンが上がると変わるので、ちょっと面倒です。
最新版 を確認して使うと良いのかなと思います。
GitHub Pagesのサイト公開の設定
GitHubに username.github.io という名前のrepositoryを作って↑の公開設定を行うと、https://username.github.io/ のURLから見れるページが作成できました。
Repository username.github.io のサブディレクトリ AAA にはファイルを配置しても意味はなく、https://username.github.io/AAA/ からはアクセスできませんでした。
Repository username.github.io のサブディレクトリ docs/AAA にファイルを配置すると、https://username.github.io/docs/AAA/ からアクセスできるようになります。
他の名前の BBB repository（パッケージのrepositoryなど）で↑の公開設定を行うと、https://username.github.io/BBB/ のURLから見れるページが作成できました。
おわりに
RStudioとGitHubさえ使えれば、Rパッケージの開発とパッケージWebサイトの公開まで超簡単にできる時代になり、隔世の感があります。
個人のHPの方はHTMLを手書きしておりますので、これからも古式ゆかしい文化を守っていく所存でございます。
ご降誕祭、おめでとうございます。
