42  Quarto：WebsiteとBook

ここまでに、QuartoでHTML、PDF、Wordなどの文書、Reveal.jsなどのプレゼンテーション、インタラクティブなダッシュボードを作成する手法を説明してきました。Quartoでは、HTMLの拡張として、ブログなどを含むWebsiteや教科書などの本のHTMLとして表現する、Bookを作成することもできます。以下にWebsiteやBookを作成する手順について、簡単に説明していきます。

42.1 Quarto project

Quartoでは、QuartoのProjectというものを設定することができます。Rstudioを用いる場合、Quarto Projectは36章で説明したRstudioのProjectとほぼ同じです。RstudioではProjectを作成するとき、Projectのタイプを選択することができます。

RStudioでProject typeを選択する

RStudioでProject typeを選択する

このリストから、「Quarto Project」や「Quarto Website」、「Quarto Book」などを選択すると、そのタイプに従ったプロジェクトと共に、いくつかの.qmdファイルがProjectのフォルダに作成されます。

Quarto Projectで作成されるファイル（Website）

Quarto Projectで作成されるファイル（Website）

Rstudioを用いている場合には、このフォルダ内の.Rprojファイルを開くとRstudioでプロジェクトが展開されます。

一方で、VSCodeなどのテキストエディタやJupyter Notebookなどを用いている場合には、RstudioのようにProjectを作成することはできません。そこで、Quarto CLIでは、TerminalからProjectを作成できるようになっています。

Quarto Projectを作成する
quarto create project

TerminalからQuarto Projectを作成すると、まずはプロジェクトのタイプを入力する画面が表示されます。タイプには、default、website、blog、manuscript、book、confluence（Wikiみたいなもの）の6つがあるので、作成する文書に対応したタイプを選択します。

次に、Directory（フォルダ名）を入力します。Directoryを入力すると、そのDirectory内にProjectが作成されます。このProjectのフォルダには、上で示した作成されるファイルから、.Rprojファイルが除かれたものが作成されます。このフォルダに移動し、quarto renderを行うと、テンプレートの文書（Websiteの場合はHTML）を作成することができます。

RstudioではProjectを作成することでいろいろな設定が行われるため、複雑な文書を作成する場合にはProjectを作成しておいた方がよいですが、VSCodeなどを用いる場合には特に必須ではなく、_quarto.ymlにYAMLの設定を書けばWebsiteやBookを特に問題なく作成することができます。ただし、Projectを作成するとテンプレートとなるファイル・フォルダを生成してくれるため、Quartoで文書の作成を始める場合には有用でしょう。

以下に、各タイプのProjectで作成されるファイル・フォルダの構造、_quarto.ymlの設定、Renderで出力されるHTMLの見ためを示します。

フォルダ構造
test_website
│- about.qmd
│- index.qmd
│- styles.css
└─ _quarto.yml
_quarto.yml
project:
  title: "test_default"

HTMLの見た目

HTMLの見た目
フォルダ構造
test_website
│- about.qmd
│- index.qmd
│- styles.css
└─ _quarto.yml
_quarto.yml
project:
  type: website

website:
  title: "test_website"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd

format:
  html:
    theme:
      - cosmo
      - brand
    css: styles.css
    toc: true

HTMLの見た目

HTMLの見た目
フォルダ構造
test_manuscript
│- references_bib
│- index.qmd
└─ _quarto.yml
_quarto.yml
project:
  type: manuscript

manuscript:
  article: index.qmd

format:
  html:
    comments:
      hypothesis: true
  docx: default
  jats: default

  # (other formats)
  # pdf: default

execute:
  freeze: true

HTMLの見た目

HTMLの見た目
フォルダ構造
test_book
│- cover.png
│- index.qmd
│- intro.qmd
│- references.bib
│- references.qmd
│- summary.qmd
└─ _quarto.yml
_quarto.yml
project:
  type: book

book:
  title: "test_book"
  author: "Norah Jones"
  date: "2025/6/13"
  chapters:
    - index.qmd
    - intro.qmd
    - summary.qmd
    - references.qmd

bibliography: references.bib

format:
  html:
    theme:
      - cosmo
      - brand
  pdf:
    documentclass: scrreprt

HTMLの見た目

HTMLの見た目
フォルダ構造
test_confluence
│- index.qmd
│- project-roadmap.qmd
│- _quarto.yml
│
└─ reports
    │- 2022-01.qmd
    └- 2022-03.qmd    
_quarto.yml
project:
  type: confluence
  title: "test_confluence"

HTMLの見た目

HTMLの見た目
フォルダ構造
test_confluence
│- about.qmd
│- index.qmd
│- profile.jpg
│- styles.css
│- _quarto.yml
│
└─ posts
    │- _metadata.yml
    │
    ├- post-with-code
    │  ├- image.jpg
    │  └- index.qmd
    │
    └- welcome
       ├- index.qmd
       └- thumbnail.jpg
_quarto.yml
project:
  type: website

website:
  title: "test_blog"
  navbar:
    right:
      - about.qmd
      - icon: github
        href: https://github.com/
      - icon: twitter
        href: https://twitter.com
format:
  html:
    theme:
      - cosmo
      - brand
    css: styles.css

HTMLの見た目

HTMLの見た目

42.2 HTMLとWebsite、Quarto Bookの違い

Quartoでは、YAMLに出力ファイルを指定せずにRenderを行うと、HTMLが出力されます。ですので、Markdown、YAMLを用いれば、ある程度自由にHTMLを用いたウェブページを作成することができます。

QuartoでWebsiteやBookを指定してWebsite・Bookを作成する利点は、ある程度出力するHTMLのデザインを固定することができる点にあります。Websiteではある程度自由に、複数の.qmdを一つのウェブページに仕立てることができます。また、Bookであれば、.qmdを各章とし、本のように一本道のウェブページを作成できます。

42.2.1 website・bookの設定

Website、Bookを作成する場合、_quarto.ymlにproject: type: websiteまたはproject: type: bookを設定します。このprojectは上記のようにQuarto Projectを作成していなくても設定可能です。

また、.qmdファイル内でprojectを設定しても、projectに応じた設定は利用できません。projectは_quarto.yml内に設定して用います。

project typeの設定
project: 
  type: website

project: 
  type: book

typeには、default、website、book、manuscriptの4つが設定できるとされていますが、上記のようにconfluenceも設定可能です。blogはwebsiteの一形態となるため、typeはwebsiteとなります。

42.2.2 index.qmd

websiteのトップページとなるのは、index.qmdという.qmdファイルです。index.qmdはbookやblogでもトップページとなります。

42.2.3 Renderする.qmdを指定する

Projectを設定した_quarto.ymlと同じフォルダ・サブフォルダ内に保存されている.qmdファイルは、そのProjectのファイルであると認識されます。このフォルダ内の.qmdファイルをRenderすると、基本的にはそのフォルダおよびサブフォルダ内のすべての.qmdファイルがRenderされます。

Projectのフォルダ内のうち、Renderしたい.qmdファイルを指定する場合には、project: render:に.qmdファイルを設定します。

Renderするファイルを指定する
project:
  render:
    - section1.qmd
    - section2.qmd

また、ファイル名の前に!を置くと、そのファイルのみを除いてRenderすることもできます。ただし、この場合には*.qmdという形で、すべての.qmdファイルを指定しておく必要があります。

Renderしないファイルを指定する
project:
  render:
    - "*.qmd" # すべての.qmdファイルをRenderする
    - "!ignored.qmd" # 選択した.qmdファイルをRenderしない
    - "!ignored-dir/" # 指定したディレクトリ内の.qmdファイルをRenderしない

42.2.4 ブログを作成する

blogはwebsiteの特殊な形の一つで、基本的なWebsiteの構造に投稿（posts）を追加して用います。blogのフォルダ構造は上に示した通り、以下のようになります。postsディレクトリ内にpostsに当たる.qmdファイルを追加していきます。

また、postsディレクトリ内にサブフォルダを作成し、その中に.qmdファイルを作成することで、各postごとのファイルをそれぞれ別に保存することもできます。

ブログのフォルダ構造
test_confluence
│- about.qmd
│- index.qmd
│- profile.jpg
│- styles.css
│- _quarto.yml
└─ posts
    │- _metadata.yml
    ├- post-with-code
    │  ├- image.jpg
    │  └- index.qmd
    └- welcome
       ├- index.qmd
       └- thumbnail.jpg

42.2.4.1 _metadata.yml

上記のpostsディレクトリ内には、_metadata.ymlというファイルがあります。これは、_quarto.ymlに設定したYAMLに加えて、postsのみに適用するYAMLを指定するためのファイルです。blogに限らず、websiteでも同様にサブフォルダ内に_metadata.ymlを設定することで、そのサブフォルダ内の.qmdのデザインやchunkの設定などをpost以外とは別の形で設定することができます。

ただし、サブフォルダ内の.qmdに適用されるYAMLは_quarto.ymlと_metadata.ymlを統合したものになり、_metadata.ymlの設定のみだけではなく、_quarto.ymlの内容も同様に適用されます。

42.2.4.2 postsの設定

各postにはタイトルや著者、登校日、ブログのカテゴリ、トップ画像を設定することができます。タイトルや著者には、39章に記載した通り、titleやauthor、dateをそのpostのYAMLに設定します。ブログのカテゴリはcategoriesに、ブログのトップ画像として用いる画像はimageにそれぞれ設定します。

Blog：PostのYAML設定
---
title: "Post With Code"
author: "Harlow Malloc"
date: "2025-06-13"
categories: [news, code, analysis]
image: "image.jpg"
---

categoriesは_quarto.ymlに以下のような形で設定することもできます。

Blog：カテゴリの設定
categories:
  - news
  - code
  - analysis

42.2.4.3 Listing

Listingとはブログのpostの一覧を表示することです。Listingはindex.qmdのページに表示されます。このListingについては、YAMLでlistingを設定することで表示を変更することができます。

Blog：投稿のlistingの設定
---
title: "myblog"
listing:
  contents: posts
  sort: "date desc"
  type: default
  categories: true
---

設定可能なYAMLの一部を以下に示します。その他の設定項目についてはQuartoのReferenceをご参照ください。

Listingに関するYAML
YAMLでの設定項目 設定項目のデータ型 設定項目の意味
type default、table、grid、custom Listingの表示のタイプ
contents サブフォルダ名 Listingに表示する記事を保存したサブフォルダ
categories true/false カテゴリを表示するかどうか
sort date asc、date desc Listingの表示順
max-items 数値 Listingに表示する記事の最大数
page-size 数値 1ページに表示する記事の数
feed true/false RSSフィードを有効にする
grid-columns 数値 表示する列の数
table-hover true/false Postをマウスで選択するとハイライトされる

42.2.4.4 Aboutページの作成

Quartoでは、著者の名前や所属、website、blogの内容などを表示するAboutのページを、postcardsパッケージ(Kross 2022)のデザインに従い設定することができます。postcardsのデザインを採用する場合、about.qmdにabout: template:のYAMLを設定します。templateには、jolla、trestles、solana、marquee、broadsideのいずれかを設定することができます。

Aboutページ
---
title: "xjorv"
image: profile.jpg
about:
  template: jolla
---

xjorvはしがない平社員のサラリーマンです。趣味としてRを触り、気まぐれに教科書を書いています。

## Education

University of bakada, Tokyo | Tokyo, Japan
Ph.D in Tunnel Science | Sept 20XX - June 20XX

42.2.4.5 RSS

Listingの説明に記載した通り、YAMLにfeed: trueを設定すると、RSSフィードを設定することができます。

RSSの設定
---
title: "a post"
listing:
  contents: posts
  feed: true
---

ただし、個別の.qmdファイルでfeed: trueと設定しただけでは、RSSを設定することはできず、_quarto.ymlで以下のようにRSSの設定を別途記載する必要があります。

RSSの設定2
website:
  title: "xjorv's blog"
  site-url: https://www.myblogexample.io
  description: "A cheap sample blog"

42.3 Quarto Book

Quartoで教科書などの本を書くときに用いるprojectのtypeがtype: bookです。bookはR markdownの拡張である、bookdown(Xie 2024)を基としたtypeで、YAMLでは以下のように記載することでbookのスタイルを適用することができます。

type: bookの設定
project:
  type: book

42.3.1 Quarto Bookの構造

Quarto Bookの構造はwebsiteと比較して単純で一本道となります。Bookの基本的な要素はindex.qmd、各章に当たる.qmdファイル、summary.qmd、reference.qmdの4つです。Quarto Bookではindex.qmdは表紙とまえがき、summary.qmdがあとがき、reference.qmdは参考文献に当たります。この3種類はQuarto Projectを用いる場合にも作成されます。

各章の.qmdファイルにはどのような名前を付けても問題ありませんが、各文書がどの章を構成するのかをYAMLで指定する必要があります。

Bookのchaptersを設定する
book: 
  chapters:
    - index.qmd
    - part: "part 1"
      chapters: 
      - chapter1.qmd
      - chapter2.qmd
    - part: "part 2"
      chapters: 
      - chapter3.qmd
      - chapter4.qmd
    - summary.qmd
    - references.qmd

上記のように設定すると、本の章立てとしては、まず始めのページがindex.qmd、次にchapter1.qmdとchapter2.qmdが「part 1」という話題の1章、2章、次のchapter3.qmdとchapter4.qmdが「part 2」の3章、4章、最後にsummary.qmdとreferences.qmdが続く形になります。要は、このchaptersのYAMLに設定した順に章が進むということになります。

ただし、章番号は上記のchapter1.qmdが1章にはならず、index.qmdが1章とされます。index.qmdを1章とせず、chapter1.qmdを1章とする場合には、index.qmdのheaderに{.unnumbered}を設定する必要があります。また、summary.qmdやreferences.qmdにもindex.qmdと同様に章番号が振られるので、番号を振りたくない場合には{.unnumbered}を設定するとよいでしょう。

ヘッダーに番号をつけない
## はじめに {.unnumbered}

42.3.2 参照（Cross references）

Quarto Bookでは、その章内の図やchunkだけでなく、他の章の記載内容を参照すること（Cross references）ができます。たとえば、以下のようにリンクを記載すると、特定の章の.qmdに対応したページへのリンクを作成できます。

章の参照
[第1章](chapter1.qmd)

[第1章](./chapter1.html) # このような形でも章へのリンクを作成できる

第1章

また、以下のようなリンクを作成することで、その章の各header（小項目）までのリンクを作成することもできます。

章内のヘッダーの参照
[第1章](chapter1.qmd#rstudioのインストール)

第1章 Rstudioのインストール

42.3.3 図・画像・表への参照

chunk optionとしてlabelを設定しておくと、そのlabelを参照し、リンクを作成することができます。また、画像や表に対しても参照を行うことができます。

ただし、参照のためのlabelの付け方にはルールがあり、図や画像のラベルはfig-から、表のラベルはtbl-から始める必要があります。また、labelにはアンダースコア（_）を用いることはできません。

```{r}
#| label: fig-cars-plot
#| filename: chunk：ラベルを設定する

plot(cars)
```
Figure 42.1 
chunkの出力を参照する
`cars`は自動車のスピードと停止するまでの距離の関係を表したデータです @fig-cars-plot 。

carsは自動車のスピードと停止するまでの距離の関係を表したデータです Figure 42.1 。

図にラベルを設定する
![大仏](./image/bud.png){#fig-bud}
  
奈良の大仏 @fig_bud
Figure 42.2: 大仏

奈良の大仏 Figure 42.2

表にラベルを設定する
+-----+-----+-----+
| pet | age | sex |
+=====+=====+=====+
| dog | 5   | F   |
+-----+-----+-----+
| cat | 3   | M   |
+-----+-----+-----+
  
: 表のラベル {#tbl-dog-cat}
  
  
表を参照する @tbl-dog-cat 。
Table 42.1: 表のラベル
pet age sex
dog 5 F
cat 3 M

表を参照する Table 42.1 。

42.4 Website・BookのRender

WebsiteやBookの.qmdを作成したら、HTMLをRenderします。Website・Bookのいずれの場合も、RStudioでは上に表示されているRenderボタンを押すことでRenderすることができます。

Renderボタン

Renderボタン

また、TerminalでProjectのフォルダに移動し、quarto renderのコマンドを実行することでもWebsite・BookをRenderすることができます。

quarto render

Renderを実行すると、Websiteではそのフォルダとサブフォルダに含まれている.qmdファイルがHTMLに変換されます。一方でBookでは、そのフォルダ内の.qmdファイルのうち、chaptersで章に設定した.qmdファイルだけがHTMLに変換されます。

42.4.1 freeze

WebsiteやBookでは、.qmdファイルを指定せずにRenderすると、変換する.qmdファイルに含まれるRのスクリプトがすべて再計算され、Renderされます。すでにHTMLを作成し、.qmdに変更がない場合にもこの再計算は実行されます。したがって、WebsiteやBookのサイズが大きくなると、再計算に時間がかかるようになります。

一度HTMLを作成した.qmdについて、ファイルに変更がない場合にRenderを実施しないようにするには、freeze: autoを設定します。また、freeze: trueを設定すると、.qmdのRenderが行われなくなります。

大きなWebsiteを作成する場合には、作成中にはfreeze: autoを用い、以下に述べるデプロイの前にはfreeze: falseとして全体をRenderするような運用を行うとよいかと思います。

freezeの設定
execute:
  freeze: auto # true/auto/falseのいずれかを選択する

大きなWebsiteやBookを作成する場合、freeze: autoはRenderにかかる時間を短縮できる便利な設定です。ただし、.qmdファイルに変更がないのに内容が変わるような場合、例えば.qmdファイル中で読み込むデータを修正した場合などには、この変更が適用されずにRenderが終了してしまいます。HTMLを共有・公開する前などには、freeze: falseに設定を変更し、Renderしたほうがよいでしょう。

Back to top