11/04/2023
A Blog Entry on Bayesian Computation by an Applied Mathematician
$$
$$
本サイトは Quarto と,GitHub Actions によってホスティングされている.
注
スマホでは別フォーマットのページのリンクは表示されないようである.
Quarto ではこのような数式・コードが共存するドキュメントが,極めて簡単に+凡ゆるフォーマットで作成できる.
計算統計の研究をしている筆者にとっては何より,数式とコードが自然に共存する PDF を簡単に書けること,そして自学のためのノートがそのまま HTML としてブログの形で公開できることが,大変嬉しかった.
特に VSCode の拡張機能と組み合わせれば,RStudio のような隙のない統合開発環境が得られる.1
基本的な仕組みとして,自分で作成するのは .qmd
ファイルのみである.
その後はquarto render
コマンドにより,
pdf
, html
, word
など好きな形式に最終出力できる.拡張機能をオンにした VSCode ではRun Cell
ボタンもあるので,ノートブック全体を毎度ビルドせずとも,コードブロックごとに実行して結果を見ることもできる.
Ctrl+Enter
で1行ごとに実行できる操作感は RStudio
と同じである.
project type
を website
としたリポジトリでquarto render
をしても,不要なファイルが自動で削除される.このような点がライトユーザーでもとにかく使いやすい.各ファイルの冒頭に YAML block を用意することで,ノートブックの詳細を調整できる(参照:HTML Options).
例えば本ページでは次のとおり:
---
title: "Quarto はじめて良かった"
author: "司馬博文"
date: "11/4/2023"
date-modified: "7/7/2024"
categories: [Lifestyle]
abstract: Quarto は TeX のような使用感で,数式とコードが併存する文章を書き,1つのソースファイルから PDF, HTML, Word, Reveal.js, PowerPoint などの多様な形式に出力できる次世代の執筆環境である.TeX, RStudio, Jupyter Notebook のいずれかに慣れている人であれば,極めて手軽に Quarto を使うことができる.
abstract-title: 概要
format:
html:
mainfont: "Gill Sans"
theme: minty
css: assets/styles.css
toc: true
number-sections: true
highlight-style: ayu
code-block-border-left: "#7CC4AC"
code-overflow: scroll
toc-title: "目次"
abstract-title: "概要"
---
本文は markdown 記法で書く.数式も使える:
\[ \operatorname{P}[\lvert\xi\rvert<t]\le2e^{-\frac{t^2}{2\sigma^2}},\qquad t>0. \]
また,コードブロックにもコメントアウトと接頭辞の組み合わせ #|
を前につけることでYAMLで指示が出せる(参照:指示のリスト).上のコードブロックには
と追加されているために,出力された図にラベリングとキャプションが付いているのである.
が必要であることに注意.
により仮想環境を作成して入れるが,この環境を Jupyter notebook で使うにはもう一手間必要である.
すると
により見つかるようになっている.YAML header で jupyter: genai
と指定すれば良い.
公式 Guide を参考.
main
と別けるまずgh-pages
という全く新しいブランチを作成する.既存のリポジトリのコミット履歴とは独立している新しいブランチを作るときは--orphan
オプションが利用される.
Terminal
基本gh-pages
ブランチには自分では立ち入らない.
Publish
コマンドによるサイトの公開main
ブランチにいることを確認して,
を実行.
GitHubの方の設定Settings: Pagesで,Sourceをgh-pages
ブランチの/(root)
にしていることを確認すれば,これで無事サイトが公開されていることが確認できる.
さらに,ローカル上でrender
するのではなく,コミットする度にGitHub上でレンダリングしてもらえるように自動化することもできる.こうするとスマホからも自分のサイトが更新できる.
まず,GitHubの設定のActionsセクションのWorkflow permissionsから,読み書きの権限をGitHub Actionに付与する.
続いて,次の内容のファイルを.github/workflows/publish.yml
に書き込む:
.github/workflows/publish.yml
on:
workflow_dispatch:
push:
branches: main
name: Quarto Publish
jobs:
build-deploy:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- name: Check out repository
uses: actions/checkout@v4
- name: Set up Quarto
uses: quarto-dev/quarto-actions/setup@v2
with:
tinytex: true # https://github.com/quarto-dev/quarto-actions/tree/main/setup
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Setting GH_TOKEN is recommended as installing TinyTeX will query the github API.
- name: Render and Publish
uses: quarto-dev/quarto-actions/publish@v2
with:
target: gh-pages
# render: false # https://quarto.org/docs/publishing/github-pages.html#additional-options
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
途中,tinytex: true
とすることで,1つのページを HTML と pdf の両方で閲覧可能になる.本ブログでは,CV のページ でこの機能を使っている.
これで,main
ブランチにコミットする度に,GitHub上でrender
が実行されることとなる.
LuaLaTeX を利用することで日本語を含んだ PDF を作成できる.
report.qmd
のような記法は,pdfLaTeX ではなぜかコンパイルが通るが,LuaLaTeX (や殆どの pdfLaTeX 以外のエンジン)ではエラーになる.
ltjsarticle
クラスでは
というエラーが.一方で,bxjsarticle
クラスでは
というエラーが出る.
ローカルではインストールすれば良いだけであるが,これを GitHub Actions 上で実現する方法を考えあぐねていた.
なぜか
で変わるのは英語文字だけである.
GitHub Actions
の修正次のようにして,Set up Quarto と Render and Publish の間に,TinyTeX と haranoaji.sty のインストールを使いすることで,GitHub 上でもレンダリングが可能になる.
publish.yml
- name: 'Install TinyTeX' # https://github.com/quarto-dev/quarto-actions/tree/main/setup
env:
QUARTO_PRINT_STACK: true
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Setting GH_TOKEN is recommended as installing TinyTeX will query the github API.
run: |
quarto install tool tinytex --log-level warning
case $RUNNER_OS in
"Linux")
echo "$HOME/bin" >> $GITHUB_PATH
export PATH="$HOME/bin:$PATH"
;;
"macOS")
TLMGR_PATH=$(dirname $(find ~/Library/TinyTeX -name tlmgr))
echo $TLMGR_PATH >> $GITHUB_PATH
export PATH="$TLMGR_PATH:$PATH"
;;
"Windows")
TLMGR_PATH=$(dirname $(find $APPDATA/TinyTeX -name tlmgr.bat))
echo $TLMGR_PATH >> $GITHUB_PATH
export PATH="$TLMGR_PATH:$PATH"
;;
*)
echo "$RUNNER_OS not supported"
exit 1
;;
esac
echo "TinyTeX installed !"
tlmgr install haranoaji # Install haranoaji.sty
shell: bash
だと,すでに TeX Live がローカルに存在する場合は,そちらにインストールされてしまう.
でインストールされる TinyTeX は,ホームディレクトリ下の ~/Liberary/TinyTeX/
の bin
内にインストールされる.1
そこの,tlmgr
がインストールされている場所まで行って,
を実行すると良い.
❯ ./tlmgr install haranoaji
tlmgr: package repository https://mirror.las.iastate.edu/tex-archive/systems/texlive/tlnet/ (verified)
[1/1, ??:??/??:??] install: haranoaji [25570k]
running mktexlsr ...
done running mktexlsr.
tlmgr: package log updated: ~/Library/TinyTeX/texmf-var/web2c/tlmgr.log
tlmgr: command log updated: ~/Library/TinyTeX/texmf-var/web2c/tlmgr-commands.log
使うフォントは次のように,Google Fonts を通じて,GitHub Actions 上でインストールすることもできるだろう:
typst の pdf は数式の処理がまだ納得のいく設定が見つかっていないが,コードの扱いが非常に自然で,出来上がりも美しい.
ただし,事前に GitHub Actions の環境上に対応する日本語フォントを用意しておく必要がある.
{yml filename="publish.yml"} - name: Install Japanese Fonts env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Setting GH_TOKEN is recommended as installing TinyTeX will query the github API. run: | git clone https://github.com/yuru7/udev-gothic.git cd udev-gothic sudo cp -r ./source /usr/share/fonts/truetype/udev-gothic sudo fc-cache -f -v