Quarto Includes

Session 4: More Quarto for Academics

Cynthia Huang

Tuesday, July 18, 2023

Advanced Quarto

Quarto Extensions

Extensions are a powerful way to modify and extend the behavior of Quarto. Types of extensions include:

• Custom Formats
• Journal Articles
• Revealjs (presentation) Plug-Ins
• Shortcode/Filters

Quarto Extensions

Extension Trust

Quarto extensions may execute code when documents are rendered. Therefore, if you do not trust the author of an extension, do not install or use the extension.

Generally safe:

• extensions maintained by the core Quarto team, or
• developed by someone you know

Quarto Includes

There are a number of ways to include and reuse existing content in Quarto documents. We’ve already covered:

• include-in* YAML options for including LaTex/HTML in header, before and after the body.
• metadata-files YAML option for reusing config files

There’s also:

• the shortcode {{< include _content.qmd >}}
• the Lua filter extension include-code-files

Reusing content

Shortcodes: Includes

See: quarto.org > Guide > Advanced > Includes

• Shortcodes are special markdown directives that generate various types of content.
• The {{< include >}} shortcode allows you to re-use content across documents.
• {{< include _snippet.qmd >}} is equivalent to copying and pasting the text from the _snippet.qmd file into the main quarto file.

Include more Quarto

Add the shortcode where you want your file to appear:

---
title: "My Document"
---

## Overview

I have some quarto content I want to reuse right here:

{{< include _basics.qmd >}}

## Another Section

More content here...

Files prefixed with underscores (e.g. _basic.qmd) are ignored when rendering a whole directory of .qmd files.

Include Text Formats

Recall that Includes are equivalent to copy and pasting text. Therefore we can also use it to include content from other text based formats (e.g. .txt, .tex, .html, .md):

---
title: "My Analysis"
---

## Results

I have some markdown content that was generated by STATA:

{{< include _stata-output.md >}}

## Acknowledgements

{{< include acknowledgements.txt >}}

What about STATA scripts?

Syntax Highlighting

Pandoc (and thus Quarto) offers syntax hightlighting in code blocks for over 140 languages, including STATA:

script.do

use "C:\data\data-sets\GSS2016.dta"
tab postlife
tab postlife sex,column 

or R:

print("Hello World")

or command line (zsh):

quarto render document.qmd --to pdf

Syntax Highlighting: STATA

• Copy your STATA code into a code block
• Add .stata to the top fence:

```{.stata filename="script.do"}
use "C:\data\data-sets\GSS2016.dta"
tab postlife
tab postlife sex,column 
```

• filename specifies a name to display above the code lines as shown on the previous slide. This is useful to showing parts of a longer script.

Aside: Executable Code Chunks

Executable R/python code chunks also have syntax highlighting, but don’t have a leading dot:

```{r}
#| eval: false
print("Hello World")
```

VS display only code-blocks

```{.r}
print("Hello World")
```

include-code-files

Syntax Highlighting for Included Files

• Copy and pasting code is both tedious and error prone.
• Unfortunately you cannot put Includes shortcodes inside code blocks:

This will not work!

```{.stata}
{{< include myjob.do >}}
```

• BUT we can include external code and use syntax highlighting with the include-code-files extension

Lua Filter Extension

The include-code-files is an Lua Filter extension developed and maintained by the core Quarto team (github.com/quarto-ext) allows you:

• to read in source files and,
• display them in code blocks with syntax highlighting.

Installing Extensions

To install:

quarto add quarto-ext/include-code-files

To use the extension add this option to either document or project metadata:

---
filters:
   - include-code-files
---

Tip

The include-code-files extension is already included in the exercises folder.

Using Extensions

To use the include-code-files extension, include the following where you want to display script.do

```{.stata include="script.do"}
```

Which will show the contents of script.do with syntax highlighting:

...
tabulate region                   /* obtain summary statistics */
summarize marriage_rate divorce_rate median_age if state!="Nevada"
...

Code Block Options

You can specify additional options separated by spaces. For example:

```{.stata include="script.do" code-line-numbers="false" filename="script.do"}
```

Note

Currently, not all HTML Code Block options work with the include-code-files extension (e.g. code-fold). You may still need to copy and paste code.

Our Turn: replication_in_parts.qmd

• Open the day01-exercises project in Rstudio.
• Open replication_in_parts.qmd.
• Render the document.

Your Turn: replication_in_parts.qmd

Continue with exercises in replication_in_parts.qmd

15:00