---
title: "Quarto Basic Template with Quick Reference"
# subtitle: "..."
date: "`r Sys.Date()`"
date-format: "iso"
author: "zenggyu"
# abstract: |
  # The abstract can span
  # over multiple lines.
  # 
  # It can also contain multiple paragraphs.
crossref:
  chapters: false
toc: true
toc-depth: 3
number-sections: true
mainfont: "Ubuntu"
monofont: "Ubuntu Mono"
code-line-numbers: true
fig-align: "center"
fig-cap-location: "bottom"
tbl-cap-location: "top"
lang: "en" # "en" for English, "zh" for Chinese
engine: "knitr"
execute:
  echo: true
  warning: false
  cache: false
editor: "source"
editor_options:
  markdown:
    canonical: false
format:
  html:
    # theme: "materia"
    toc-location: "left"
    embed-resources: true
    anchor-sections: true
    smooth-scroll: true
    email-obfuscation: "javascript" # or "references", "none"
    code-fold: false
    code-overflow: "scroll"
    link-external-icon: true
    link-external-newwindow: true
    citations-hover: true
    footnotes-hover: true
    strip-comments: true
    self-contained-math: false
    reference-location: "margin" # or "block", "section", "margin"
    knitr:
      opts_chunk:
        R.options:
          tibble.width: 256
          tibble.print_max: 128
    # filters:
    #   - lightbox # quarto install extension quarto-ext/lightbox
    # lightbox:
    #   match: "auto"
#   revealjs:
#     # institute: "..."
#     theme: "default"
#     incremental: false
#     slide-level: 2
#     slide-number: true
#     center-title-slide: true
#     # logo: "path-to-logo.png"
#     scrollable: true
#     smaller: true
#     overview: true
#     menu: true
#     chalkboard: true
#     transition: "slide"
#     progress: true
#     navigation-mode: "vertical"
#     self-contained-math: false
#   pdf:
#     pdf-engine: "xelatex"
#     CJKmainfont: "Noto Sans CJK SC" # Download extra fonts from: https://www.fonts.net.cn/; list available fonts with `fc-list` in Bash.
#     documentclass: "scrreprt"
#     papersize: "a4"
#     knitr:
#       opts_chunk:
#         dev: "cairo_pdf"
#   docx:
#     reference-doc: "MS-Word.docx"
# nocite: "@*"
# # csl: "path-to-CSL-file.csl" # or a link to a CSL file, e.g., "https://www.zotero.org/styles/ieee?source=1"
# # bibliography: "path-to-BibTeX-file.bib" # or with manual entries like below
# references:
#   - id: "RstudioQuartoGuide2022"
#     title: "Quarto - Guide"
#     author:
#       - family: "RStudio"
#         given: "PBC"
#     url: "https://quarto.org/docs/guide/"
#     issued:
#       year: 2022
#   - id: "RstudioQuartoReference2022"
#     title: "Quarto - Reference"
#     author:
#       - family: "RStudio"
#         given: "PBC"
#     url: "https://quarto.org/docs/reference/"
#     issued:
#       year: 2022
#   - id: "MacFarlanePandocUserGuide2022"
#     title: "Pandoc User's Guide"
#     author:
#       - family: "MacFarlane"
#         given: "John"
#     url: "https://pandoc.org/MANUAL.html"
#     issued:
#       year: 2022
---

```{r}
#| echo: false

library(tidyverse)
```

# Basics

- Markdown basics: <https://quarto.org/docs/authoring/markdown-basics.html>
- Pandoc markdown particularities (relevant for using Quarto visual editor): <https://quarto.org/docs/visual-editor/markdown.html>

# Text

::: {style="text-align: center"}
Text style can be adjusted with the style attribute of the enclosing div block, e.g., `::: {style="text-align: center"}`.

Text can also be partly styled using the span syntax, e.g., [\[small gray text\]\{style="font-size: 60%; color: slategray"\}]{style="font-size: 60%; color: slategray"}.

:::

# Figures

Figures can be added manually using `![<caption>](path-or-url>){#fig-<id> [<attribute> ...]}`. Additionally, the alignment and width of the figure can be adjusted with the `fig-align` and `width` attribute. For example:

![An image](https://images.rawpixel.com/image_1000/czNmcy1wcml2YXRlL3Jhd3BpeGVsX2ltYWdlcy93ZWJzaXRlX2NvbnRlbnQvd2s4MDQyMzk0Mi1pbWFnZS1rcDZjaXRqYS5qcGc.jpg){#fig-an-image fig-align="center" width="80%"}

Figures can also be generated with code. To set the figure id, use option `label: "fig-<id>"`. For example:

```{r}
#| code-summary: "Generate a scatter plot"
#| label: "fig-a-scatter-plot"
#| fig-cap: "A scatter plot."
#| fig-align: "center"
#| fig-width: 7 # default, same with fig-height
#| out-width: "100%" # or "400px", etc. same with out-height
#| fig-asp: 0.714 # (height/width) default
#| echo: "fenced"

plot(mtcars$hp, mtcars$mpg)
```

# Tables

Quarto supports two kinds of markdown tables: pipe tables and grid tables. While pipe tables are the simpler and more common, grid tables are more advanced and allow arbitrary block elements (multiple paragraphs, code blocks, lists, etc.). To assign a a table id for cross reference, add a caption to the table then include a `#tbl-<id>` label in braces at the end of the caption. For example, the first table below is a pipe table,

| Default | Left | Right | Center |
|---------|:-----|------:|:------:|
| 12      | 12   |    12 |   12   |
| 123     | 123  |   123 |  123   |
| 1       | 1    |     1 |   1    |

: A pipe table. {#tbl-a-pipe-table tbl-colwidths="[25, 25, 25, 25]"}

while the second one is a grid table.

+---------------+---------------+--------------------+
| Fruit         | Price         | Advantages         |
+:=============:+==============:+:===================+
| Bananas       | $1.34         | - built-in wrapper |
|               |               | - bright color     |
+---------------+---------------+--------------------+
| Oranges       | $2.10         | - cures scurvy     |
|               |               | - tasty            |
+---------------+---------------+--------------------+

: A grid table. {#tbl-a-grid-table tbl-colwidths="[30, 30, 40]"}

Tables can also be generated with code, using functions such as `knitr::kable()` and `gt::gt()`. To set the table id, use option `label: "tbl-<id>"`. For example:

```{r}
#| code-summary: "Generate a table"
#| label: "tbl-mtcars"
#| tbl-cap: "The mtcars dataset"
#| echo: fenced

knitr::kable(head(mtcars))
```

# Theorems

To include a reference-able math definition, create a div with a `#def-<id>` label (or one of other theorem-type labels including `#thm-<id>`, `#lem-<id>`, `#cor-<id>`, `#prp-<id>`, `#cnj-<id>`, `#exm-<id>` and `#exr-<id>`). For example:

::: {#def-a-definition}

$$
y = ax + b
$$

:::

# Layouts

## Column types

Quarto uses the concept of columns to describe page layout, and some types of columns have wider width than others:

1. `::: {.column-body}` (the default):

::: {.column-body .border style="text-align: center; background-color: firebrick; opacity: 0.1;"}
\
:::

2. `::: {.column-page-inset}`:

::: {.column-page-inset .border style="text-align: center; background-color: seagreen; opacity: 0.1;"}
\
:::

3. `::: {.column-screen-inset}`:

::: {.column-screen-inset .border style="text-align: center; background-color: steelblue; opacity: 0.1;"}
\
:::

## Complex layouts

Quarto supports much more complex layouts for figures, tables and text (indicated by headings, e.g., `#`, `##`, etc.) objects. For example:

:::::: {.columns .column-body}

::::: {.column width="50%"}

:::: {#fig-images layout="[[50, 50], [100]]" layout-valign="center"}

![Image A](https://images.rawpixel.com/image_800/czNmcy1wcml2YXRlL3Jhd3BpeGVsX2ltYWdlcy93ZWJzaXRlX2NvbnRlbnQvbHIvZnJjYXRfbWlhX2JsdWVfY2F0XzAtaW1hZ2Uta3liZTBwaWguanBn.jpg){#fig-image-a fig-align="center"}

::: {layout="[[25], [25]]"}

![Image B](https://images.rawpixel.com/image_1000/czNmcy1wcml2YXRlL3Jhd3BpeGVsX2ltYWdlcy93ZWJzaXRlX2NvbnRlbnQvbHIvdXB3azc2NTc1NjY0LXdpa2ltZWRpYS1pbWFnZS1rb3dzNzl0ei5qcGc.jpg){#fig-image-b fig-align="center"}

![Image C](https://images.rawpixel.com/image_1000/cHJpdmF0ZS9sci9pbWFnZXMvd2Vic2l0ZS8yMDIyLTA1L2ZsNDIzOTk2MTEyMzUtaW1hZ2Uta3R4dDY0Y3AuanBn.jpg){#fig-image-c fig-align="center"}

:::

![Image D](https://images.rawpixel.com/image_1000/czNmcy1wcml2YXRlL3Jhd3BpeGVsX2ltYWdlcy93ZWJzaXRlX2NvbnRlbnQvbHIvZnJjYXRfYXV0dW1uX2FuaW1hbF9vdXRkb29ycy1pbWFnZS1reWNocXMzMi5qcGc.jpg){#fig-image-d fig-align="center"}

Four cats
::::

:::::

::: {.column width="1%"}
<!-- placeholder -->
:::

::: {.column width="49%"}

```{r}
#| code-summary: "Generate multiple plots with complex layout"
#| label: fig-scatter-plots
#| fig-cap: "Two scatter plots"
#| fig-subcap:
#|   - "Scatter plot A"
#|   - "Scatter plot B"
#| layout: "[[1], [1]]"
#| echo: false

plot(mtcars$qsec, mtcars$mpg)
plot(mtcars$wt, pressure$mpg)
```

:::

::::::

Here is another example:

::::: {.columns}

:::: {.column width="50%"}

![](https://img.icons8.com/fluency/2x/kitty.png){width="20%" fig-align="center" style="margin-bottom: 0px"}

::: {style="text-align: center"}
[**1**]{style="font-size: 200%"} cat
:::

::::

:::: {.column width="50%"}

![](https://img.icons8.com/fluency/344/pets.png){width="20%" fig-align="center" style="margin-bottom: 0px"}

::: {style="text-align: center"}
[**1**]{style="font-size: 200%"} cat and [**1**]{style="font-size: 200%"} dog
:::

::::

:::::

And another:

::::: {.columns}

:::: {.column width="10%"}

![](https://img.icons8.com/fluency/2x/bird.png){width="100%" fig-align="right"}

::::

:::: {.column width="40%"}

::: {style="text-align: left"}
- some text...
- more text...
:::

::::

:::: {.column width="10%"}

![](https://img.icons8.com/fluency/2x/fish.png){width="100%" fig-align="right"}

::::

:::: {.column width="40%"}

::: {style="text-align: left"}
- some text...
- more text...
:::

::::

:::::

{{< pagebreak >}}

# Cross-references {#sec-cross-references}

To reference an article:

- [@RstudioQuartoGuide2022; @RstudioQuartoReference2022]
- or @RstudioQuartoGuide2022

To reference (sub-)figures, (sub-)tables, theorems and sections (note that generated sub-figures/tables can only be referenced with `@fig-<id>-<number>`/`@tbl-<id>-<number>`):

- @fig-an-image
- @fig-images, @fig-image-a, @fig-scatter-plots, @fig-scatter-plots-1, @fig-scatter-plots-2
- @tbl-a-pipe-table
- @def-a-definition
- @sec-cross-references

{{< pagebreak >}}

# Callouts

There are five different types of callouts available: `note`, `warning`, `important`, `tip`, `caution`. They can be created via a markdown div with the class name callout-* (e.g., `::: {.callout-note}`).

The title of a callout can be optionally changed by adding a header inside the block (e.g., `# Title`).

A callout can be made to be collapsible by adding `collapse="true"` to the div block (HTML only).

::: {.callout-note}
This is a note.
:::

::: {.callout-tip}
This is a tip.
:::

::: {.callout-warning}
This is a warning.
:::

::: {.callout-important}
This is an important message.
:::

::: {.callout-caution collapse="true"}
## Collapsed callout with custom title
This is a caution.
:::

{{< pagebreak >}}

:::: {.content-visible when-format="html"}

# Tabsets (HTML only)

Tabsets can only be used in HTML (including revealjs) output. They can be created via a markdown div with the class name panel-tabset (e.g., `::: {.panel-tabset}`). Individual tabs are created using headers inside the block (e.g., `#`, `##`, etc.).

::: {.panel-tabset}

## A tab {.unnumbered .unlisted}

Some content.

## Another tab {.unnumbered .unlisted}

More content.

:::

{{< pagebreak >}}

::::

# Extensions

Extensions should be **installed in the working directory**, using either `quarto install extension <gh-org>/<gh-repo>` (install from a GitHub repo) or `quarto install extension <path-to-zip>` (install from a local zip file).

Below is a list of some frequently used extensions and their yaml headers.

- [Lightbox](https://github.com/quarto-ext/lightbox) (lightbox styling and behavior to images in HTML documents) (`quarto install extension quarto-ext/lightbox`)

    ```
    filters:
        - lightbox
    lightbox: "auto"
    ```

- [Elsevier](https://github.com/quarto-journals/elsevier) (a journal template) (`quarto install extension quarto-journals/elsevier`)

    ```
    format:
      elsevier-pdf:
        journal:
          formatting: "preprint"
          model: "3p"
          layout: "twocolumn"
          cite-style: "numbered"
          graphical-abstract: "![](abstract.png)"
          highlights:
            - "Highlight 1"
            - "Highlight 2"
            - "Highlight 3"
    ```

# Miscellaneous

- A line break is represented by a `\` character.
- A page break is represented by a `{{{< pagebreak >}}}` shortcode. <!-- Note: the effective shortcode is {{< pagebreak >}}; the preceding one is an escaped shorcode with three curly brackets. -->
- To embed downloadable files, use `xfun::embed_file()`, `xfun::embed_files()` or `xfun::embed_dir()`.

# Appendix {.appendix .unnumbered}

This is an appendix. It is created using a header with class name appendix (usually together with class name unnumbered, e.g., `# Appendices {.appendix .unnumbered}`).

Place custom CSS code block at the end of the document to avoid unintended execution during interactive development (e.g., when clicking the "Run all chunks above" button in RStudio).

```{css}
#| echo: false

.cell-output code {
  white-space: pre; /* or pre-wrap, pre-line*/
  border: 1px dashed grey;
  padding: 1em;
  background-color: #FEFEFE
}
```
