6 Productivity Hacks for Quarto

This article is originally published at https://www.rstudio.com/blog/

Quarto is an open-source scientific and technical publishing system built on Pandoc. With Quarto, you can render plain text and mixed formats into static HTML pages, PDFs, Word documents, websites, and more. Over the past months, we’ve been delighted to see an explosion of Quarto use, from the publication of books to the creation of widgets.

In this post, we wanted to highlight six productivity hacks for Quarto. We hope they are useful to you as you create content.

1. Automate insertion of Pandoc Divs and Spans with snippets
2. Write verbatim code chunks with echo: fenced
3. Use shortcodes for simple insertion of content
4. Convert chunk options with knitr::convert_chunk_header()
5. Re-use content across documents
6. Automate Quarto publishing with GitHub Actions

Automate insertion of Pandoc Divs and Spans with snippets

In Quarto documents, you can use Pandoc Divs and Spans to add classes, attributes, and other identifiers to regions of content. For example, we can add a border around the text using a div:

::: {.border}
This content can be styled with a border
:::

This will render as:

A Span provides attributes to inline text:

[This is *some text*]{.class key="val"}

Snippets are a great way to automate inserting code. Thomas Mock provides a Gist with snippets for frequently-used Divs and Spans, making it much faster to include them in your Quarto documents:

Add them to RStudio by navigating to Tools > Global Options > Code > Edit Code Snippets:

Make sure to add the snippets to the “Markdown” section of the snippet editor:

Note that you use Shift + Tab instead of Tab to autocomplete within Quarto documents:

The same Gist includes snippets for VS Code. Add them by going to the Command Palette Cmd + Shift + P, type “configure user snippets”, create a snippet .json file, and insert the snippets:

Within a .qmd file, call “Insert snippet” from the Command Palette and select the respective snippet.

Write verbatim code chunks with echo: fenced

When you render a code chunk within a Quarto document, you see the code contained within the chunk and the executed output by default:

However, you do not see the fenced chunk itself — that is, the ```{python} portion. Seeing the chunk options can be helpful, especially when showing someone else how to format their document. You can do this using the echo: fenced option. For example, the following code chunks:

```{r}
data("penguins", package = "palmerpenguins")
```

```{python}
#| echo: fenced
penguins=r.penguins
penguins
```

Will render as:

If you would like to include an unexecuted fenced code block, you can do this by using two curly braces around the language rather than one. For example:

```{{python}}
penguins=r.penguins
penguins
```

Will render as:

Notice the data frame is not printed.

Learn more in the Quarto documentation, Execution Options.

Use shortcodes for simple insertion of content

Often, we add raw HTML (e.g., a video <iframe>) to insert templates or content into our Markdown documents. Shortcodes simplify the syntax and make it easier to insert what we want.

Quarto supports several shortcodes natively. For example, running the code below:

---
title: "My Blog Post"
---

My blog post is called {{< meta title >}}.

Will render as:

Authors can write and distribute their own shortcodes. For example, Mark Sellors’ Quarto Social Embeds provides shortcodes for YouTube videos, Twitter, and more.

The shortcode:

---
title: "Welcome to Quarto Workshop"
---

{{< youtube yvi5uXQMvu4 >}}

Will render as:

Shortcodes are a type of Quarto extension. Find out more in the Extensions chapter of the Quarto documentation and check out a list of available extensions in the Awesome Quarto list.

Convert chunk options with knitr::convert_chunk_header()

In the 1.40 release of knitr, a new function called convert_chunk_header() converts the old in-header chunk options to the new in-body chunk options. Note that you can use the old syntax in Quarto; however, we recommend using the new syntax to make documents more portable and consistent across execution engines.

You can explicitly name the output:

convert_chunk_header("test.Rmd", output = "test2.Rmd")
convert_chunk_header("test.Rmd", output = "test3.qmd")

Or overwrite the input:

convert_chunk_header("test.Rmd", output = identity)

This function saves time converting to the new syntax.

Re-use content across documents

Includes is a shortcode that allows you to reuse content across documents without copying and pasting. To include a file, add {{< include >}} at the location in your document where you want it included (note the underscore _ prefix for the included file):

{{< include _content.qmd >}}

You can also conditionally include content. Make content visible when rendering to a particular format using the .content-visibleclass in a Div. Or, hide content when rendering to a particular format using the .content-hidden class.

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

Will only appear in HTML.

:::

Learn more about Includes and conditional content in the Quarto documentation.

Automate Quarto publishing with GitHub Actions

GitHub Actions is a platform that allows you to automate your deployment pipeline. For Quarto users, GitHub Actions can be helpful so you do not have to remember to render your document every time you push up to your repository.

The Quarto Actions repository provides YAML workflow files to serve as templates.

Learn More

We hope that you are enjoying Quarto and that these hacks are helpful to you! To learn more, check out:

• News, tips, and commentary from the Quarto blog
• A Quarto tip a day by Mine Çetinkaya-Rundel

Interested in learning how to make Quarto content? Watch our YouTube playlist of the Quarto Series. There are in-depth walkthroughs introducing Quarto, showing how to build a blog, and create beautiful reports and presentations.

Thanks for visiting r-craft.org
This article is originally published at https://www.rstudio.com/blog/
Please visit source website for post related comments.