Github ActionsでQuartoのコードリンク機能を有効にする方法

r
quarto
Github ActionsでQuartoのwebsiteをビルドする際に、コードリンク機能を有効にする方法についてのメモです
Published

2026-01-29

Modified

2026-01-29

Quartoでウェブサイトを作成する際に、code-linkオプションを有効にしていても、Github Actionsでビルドした際にコードリンクが機能しませんでした。 この問題を解決した際のメモを残します。 まとまりのない文章になってしまっていること、あらかじめご了承ください。

Caution

code-linkオプションはknitrエンジンのみでサポートされています。 そのため、Rコードブロックでのみ機能します。

code-linkオプションとは

code-linkオプションは、Quartoのコードブロック内で使用されている関数にドキュメントリンクを自動的に追加するためのオプションです。 このオプションを有効にすると、コードブロック内の関数名がリンク付きで表示され、対応するドキュメントページに移動できるようになります。

例えば、plot()と書くと、関数にマウスを合わせた際にリンクが表示され、クリックするとRの公式ドキュメントのplot()関数のページに移動します。 うまくリンクが追加されているでしょうか。

Note

code-linkオプションについては以下の公式ドキュメントを参照してください。

現在の状況

現在、Github ActionsでQuartoのwebsiteをビルドしています。

Note

GitHub ActionsでQuartoのwebsiteをビルドする方法については、以下の公式ドキュメントを参照してください。

_quarto.ymlファイルを一部抜粋します。

_quarto.yml
format:
  html:
    code-link: true
    code-line-numbers: false 
    code-annotations: false

これでcode-linkは有効化されるはずです。 実際に、ローカル環境でビルドした際には、コードブロック内の関数にドキュメントリンクが追加されていました。

しかし、Github Actionsでビルドした際には、コードリンクが追加されていませんでした。 実際にソースコードを確認したところ、関数へのリンクが生成されていませんでした。

考えられる原因と解決策

GitHub Actionsのビルドでは、code linkingに必要なdownlitパッケージがうまく動作していないのではないかと考えました。

そこで、以下のように.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

      - name: Install R
        uses: r-lib/actions/setup-r@v2
        with:
          r-version: "4.5.2"

      - name: Install system dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y \
            libpng-dev \
            libjpeg-dev \
            libtiff-dev \
            libfftw3-dev \
            libglpk-dev \
            libx11-dev \
            libxt-dev \
            pandoc

      - name: Install R Dependencies
        uses: r-lib/actions/setup-renv@v2
        with:
          cache-version: 1

      - name: Render and Publish
        uses: quarto-dev/quarto-actions/publish@v2
        with:
          target: gh-pages
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

これは、QuartoドキュメントのExample: Knitr with renvを参考にしつつ、生じたエラーをもとに調整したものです。

r-version: "4.5.2"とInstall system dependenciesの部分が具体的な変更点です。

具体的な解決までの流れ

以下に具体的な流れを示します。

1. freezeの確認

_quarto.yml内でfreeze: autoが設定されていることを確認します。

_quarto.yml
execute:
  freeze: auto
Note

freezeオプションについては以下の公式ドキュメントを参照してください。

その後、一度ローカル環境でサイトをレンダリングします。

Terminal
quarto render

レンダリング後、_freezeフォルダが生成されていることを確認します。

2. renvのセットアップ

まだrenvを使用していない場合、プロジェクトにrenvをセットアップします。 もし、renvパッケージがインストールされていない場合、以下のコマンドでインストールします。

install.packages("renv")
Note

renvパッケージについては以下の公式ドキュメントを参照してください。

インストールが完了したら、以下のコマンドでrenvを初期化します。

renv::init()

renvが初期化されると、プロジェクトにrenv.lockファイルなどの関連ファイルやフォルダが生成されます。 これらのファイルはGitHubリポジトリにコミットします。

Note

renv/libraryなどはrenv/.gitignoreに含まれているため、コミットされません。デフォルトのままコミットして構いません。

3. 公開用サイトの初期化とブランチの作成

以下のコマンドを実行します。

Terminal
quarto publish gh-pages

4. Github Actionsワークフローファイルの作成

.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

      - name: Install R
        uses: r-lib/actions/setup-r@v2
        with:
          r-version: "4.5.2"

      - name: Install system dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y \
            libpng-dev \
            libjpeg-dev \
            libtiff-dev \
            libfftw3-dev \
            libglpk-dev \
            libx11-dev \
            libxt-dev \
            pandoc

      - name: Install R Dependencies
        uses: r-lib/actions/setup-renv@v2
        with:
          cache-version: 1

      - name: Render and Publish
        uses: quarto-dev/quarto-actions/publish@v2
        with:
          target: gh-pages
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

このファイルで行っていることを簡単に列挙すると以下の通りです。

  • リポジトリのチェックアウト
  • Quartoのセットアップ
  • Rのインストール
  • 必要なシステム依存関係のインストール
  • renvを使用してRパッケージのインストール
  • Quartoドキュメントのレンダリングと公開

また、以下の部分のRのバージョンについては、renvで使用しているRのバージョンに合わせることで、問題が起こりにくくなると思います。

.github/workflows/publish.yml
      - name: Install R
        uses: r-lib/actions/setup-r@v2
        with:
          r-version: "4.5.2"

また、Install system dependenciesの部分はエラーを見ながら追加した部分ですが、その他エラーを見ながら調整してください。

.github/workflows/publish.yml
      - name: Install system dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y \
            libpng-dev \
            libjpeg-dev \
            libtiff-dev \
            libfftw3-dev \
            libglpk-dev \
            libx11-dev \
            libxt-dev \
            pandoc

5. Githubリポジトリへのコミットとプッシュ

ここまでの変更をGithubリポジトリにコミットし、プッシュします。

Terminal
git add .
git commit -m "Set up GitHub Actions for Quarto with code-linking"
git push origin main

私は最近はGitHub Desktopを使用しているため、GUIでコミットとプッシュを行いました。

これで、GitHub Actionsがトリガーされ、Quartoのwebsiteがビルドされます。 GitHub上でActionsタブを確認します。

公式ドキュメントの例では、Install system dependenciesの部分は入っていません。

しかし、私の環境ではこの部分を追加しないとInstall R Dependenciesの部分でエラーが生じ、ビルドが失敗しました。

具体的には、Error: Error: Error installing package 'tiff':のようなエラーが発生しました。

このようなエラーが生じたら、Install system dependenciesの部分を追加してみてください。

例えば、Error: Error: Error installing package 'tiff':のエラーが生じたときには、libtiff-devを追加することで解決しました。

.github/workflows/publish.yml
      - name: Install system dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y \
            libtiff-dev \

このような試行錯誤を何度か繰り返し、最終的な.github/workflows/publish.ymlファイルが先述のように完成しました。

Note

これらのビルドのためのActionでは一回で約8分くらいかかりました。 粘り強い試行錯誤が必要になるかもしれません。 私の書いた.github/workflows/publish.ymlファイルがそのまま使えるかはわかりませんが、参考にしてみてください。

6. downlitとxml2パッケージのrenvへの追加

ここまでの手順で、Github ActionsでQuartoのwebsiteをビルドした際に、エラーは生じず、コードリンクが正しく機能すると考えていましたが、これでもうまくいきませんでした。

Render and Publishのステップで以下のような警告が出ていました。

Warning message:
The downlit and xml2 packages are required for code linking

どうやら、ローカルの環境には含まれているものの、GItHub Actionsのビルド環境には明示的依存として認識されていなかったようです。

そこで、レンダリングする.qmdファイルの先頭に以下のように追記しました。

renv::install(c("downlit", "xml2"))
library(downlit)
library(xml2)
renv::snapshot()

この状態でいったんローカルでビルドし、renv.lockファイルが更新されたことを確認します。 その後、renv.lockファイルをGitHubリポジトリにコミットし、プッシュします。 このとき、GitHub Actionsのログを確認すると、先ほどの警告は生じないことがわかりました。 また、実際にGithub上でビルドされたwebsiteを確認すると、コードリンクが正しく機能していることがわかりました。

その後、先ほど挿入した

renv::install(c("downlit", "xml2"))
library(downlit)
library(xml2)
renv::snapshot()

を消去しても問題なくコードリンクが機能していました。

Note

このやり方が最適なのかはわかりませんが、私の場合はこれでうまくいきました。 もっと良い方法があるのかもしれません。

最後に

とりとめのない文章になってしまいましたが、Github ActionsでQuartoのwebsiteをビルドする際に、コードリンク機能を有効にする方法についてのメモを残しました。 この記事が同じ問題に直面している方の参考になれば幸いです。