Quarto

Commonly used commands after setup

quarto preview  # to preview the website
quarto render  # to render the website (recommanded before push)

Use quarto preview or shift+cmd+k to preview side-by-side.

When publishing from gh-pages instead of the _docs directory, use quarto publish gh-pages in the "main" branch.

Use VS Code Notebook Editor for publishing with Quarto

Cross references

Cross-reference can also be created in float or with division

Book Crossrefs

Code content

There are several ways to publish content that includes code. For a simple blog post, we can embed code (and their corresponding results) directly into its qmd file. Alternatively, we can create a separate Jupyter notebook and embed parts of it and its results into the blog’s qmd file.

For more comprehensive projects, we might consider other formats offered by Quarto, such as Manuscripts and Books. For instance, a quarto manuscript has an article view that only shows the results of code execution (like graph visualizations) in the article body, and ook view that reveals all the underlying notebook code. This is includes the notebook version of the article itself, along with additional notebooks as needed. It is essentially a qmd file creating the index page with embedded cells from companion Jupyter notebooks. We can also download these notebooks directly. In comparison, Quarto books support multiple chapters and cross-referencing in their HTML format. They also provide a normal view with its companion source code repository.

Manuscripts and Books are really just different Quarto project types that have their customized behavior, similar to other types like website and blogs. A key file that specifies the behaviro is the _quarto.yml configuration file.

using `qmd` or `ipynb`?

Both file formats allow us to embed code. The following guidelines can be helpful:

If the subject is primarily a non-coding topic and we are simply embedding code to supplement the presentation, such as creating graph visualizations, then it is good to go with the qmd and embed code in it.
If the subject is primarily a coding topic, it is easier to start with ipynb natively.

For qmd files, it is easier to go with VSCode or text editors like NeoVim. For ipynb files, Jupyter Lab/notebook is the native approach, but VSCode also offers surprisingly good Notebook Editor.

Here are examples of authoring a manuscript in qmd with VSCode and in ipynb in Jupyter Lab.

Tex errors

If compilation fails, quarto publish gh-pages will not publish to the website!

If quarto render reports Tex related errors, check the index.tex and index.log file.

! LaTeX Error: Something's wrong--perhaps a missing \item.

# References {.unnumbered}

::: {#refs}
:::

This could be the cause.

❯ grep -n -A 1 '\\begin{itemize}\|\\begin{enumerate}\|\\begin{description}' index.tex

Draft setting bugs

The latest Quarto 1.5 seems to have bugs with setting posts as drafts. After each rendering and preview the drafts posts will re-appear in the list. One way to get rid of it is to comment out or add back the drafts: attribute of the frontmatter in the list qmd file or the site’s _quarto.yml file.

But this could reset the custom domain setting and may require adding the custom domain again.

Quarto slides

Note: We can use the following to have

format: 
  # html: default
  revealjs:
    multiplex: true
    self-contained: true
    slide-number: true
    # chalkboard: 
    #   buttons: false
    preview-links: auto

Then it will produce a local index-speaker.html used for presentation, and an index.html on server for download.

Note:

ERROR: Reveal plugin ’RevealChalkboard is not compatible with self-contained output

Quarto subscription

Blogging with Quarto and Jupyter: The Complete Guide

Adding Subscriptions to a Quarto Site