Quarto

Workflow

Build and render the project using:

quarto render && quarto preview

Tip

This assumes that Quarto is installed, or you are running in the dev container.

Website Config

Here the the main YAML config for the site:

---
project:
  type: website
  title: "Cameron's git-site"
  output-dir: docs

resources:
  - "presentations/math-magic/videos/*"

profile:
  group:
    - [base, cpp, python, devops, onepager]

format:
  html:
    theme:
      light: flatly
      dark: darkly
    default: true
    toc: true
    toc-depth: 4

execute:
  eval: false
  warning: true
  error: true
  echo: true
  cache: true
  freeze: true

website:
  repo-url: https://github.com/cameronrutherford/cameronrutherford
  repo-actions: [edit]
  search:
    type: overlay
  navbar:
    search: true
    left:
      - text: "CV"
        file: resume/resume.qmd
      - text: "Site Configuration"
        menu:
          - config/devcontainer.qmd
          - config/github-actions.qmd
          - config/pre-commit.qmd
          - config/quickstart.qmd
          - config/quarto.qmd
      - text: "C++ Coding Interview"
        menu:
          - blog/cpp-coding-interview/00-gettingStarted.qmd
          - blog/cpp-coding-interview/01-testConfiguration.ipynb
          - blog/cpp-coding-interview/02-leetCode1095.ipynb
          - blog/cpp-coding-interview/03-leetCode2742.ipynb
      - text: "Python Coding Interview"
        menu:
          - blog/python-coding-interview/00-gettingStarted.qmd
          - blog/python-coding-interview/01-testConfiguration.ipynb
          - blog/python-coding-interview/02-leetCode1425.ipynb
          - blog/python-coding-interview/03-leetCode1793.ipynb
      - text: "CUDA Coding Interview"
        menu:
          - blog/CUDA-coding-interview/01-testConfiguration.ipynb
      - text: "Presentations"
        menu:
          - presentations/stem-engagement/presentation.qmd
          - presentations/math-magic/presentation.qmd
          - presentations/c++-loops-interview/presentation.qmd
    tools:
      - icon: twitter
        href: https://twitter.com/cam_rutherford_
        text: Quarto Twitter
      - icon: github
        href: https://github.com/cameronrutherford
        text: Quarto GitHub
      - icon: linkedin
        href: https://www.linkedin.com/in/robert-c-rutherford/
        text: LinkedIn

As you can see, some other configuration is also specified, such as the HTML theme, navbar config, and the output dir.

Output Formats

RevealJS

Most of the presentations are in this format.

GFM

The main README.md is rendered into gfm and then copied into the right location in git. Check the source file of index.qmd for a small easter egg/bugg.

PDF

Font Styles

To view available font names that LaTeX can pick up on, run:

fc-list  | cut -d\  -f2-99 | cut -d: -f1 | sort -u

From https://stackoverflow.com/questions/5109550/how-to-get-a-list-of-all-available-ttf-fonts-with-xetex.

Installing a Font

This proved too difficult and so TODO for now.

Supporting LaTeX

To support pdfs, you need a TeX installation. Here is a sample error that you get when you do not have this:

No TeX installation was detected.

Please run 'quarto install tinytex' to install TinyTex.
If you prefer, you may install TexLive or another TeX distribution.

You could have installed with the TeXlive Spack package, but why introduce more complication - instead the Dockerfile installs per TeXLive install instructions.

tlmgr

After installing Tex Live, I then tried rendering for the first time, and got the following error:

Rendering PDF
running xelatex - 1
  This is XeTeX, Version 3.141592653-2.6-0.999995 (TeX Live 2023) (preloaded format=xelatex)
   restricted \write18 enabled.
  entering extended mode

updating tlmgr

updating existing packages
finding package for tcolorbox.sty
> 1 package to install
> installing tcolorbox (1 of 1)
ERROR: tlmgr returned a non zero status code
You don't have permission to change the installation in any way,
specifically, the directory /usr/local/texlive/2023/tlpkg/ is not writable.
Please run this program as administrator, or contact your local admin.
tlmgr: An error has occurred. See above messages. Exiting.


Stack trace:
You don't have permission to change the installation in any way,
specifically, the directory /usr/local/texlive/2023/tlpkg/ is not writable.
Please run this program as administrator, or contact your local admin.
tlmgr: An error has occurred. See above messages. Exiting.

    at asErrorEx (file:///quarto-1.4.251/bin/quarto.js:13087:16)
    at logError (file:///quarto-1.4.251/bin/quarto.js:25798:17)
    at file:///quarto-1.4.251/bin/quarto.js:110160:13
    at eventLoopTick (ext:core/01_core.js:181:11)

So, I googled and updated tlmgr in the end with tlmgr update --self && tlmgr update --all in the Dockerfile (See SO Post), and then had to iteratively add any remaining dependencies.

Extensions

These all are installed manually from the command line, and are not included in the Dockerfile. This is because the whole extesion ecosystem works through the _extensions directory. See Quarto Extensions.

To install the first extension, I ran:

quarto add --no-prompt quarto-ext/include-code-files

Extension List

Note that these are the only project-wide extension installed. Other custom extensions can be installed for individual documents as needed, such as for my stem engagement presentation where I added a blackboard theme.

Quarto Misc

Note

I included the old github markdown resume in old_resume.qmd in the HTML of my main resume using the following quarto snippet:

{{< include <file_to_include>.qmd >}}

Make sure to change to the correct file when copying for your own use.

Tip

Check out the source code for this if you haven’t already in the side bar.

In order to render quarto source code without rendering it in a document, you have to add another { } to your source code, and use a markdown source comment.

I rendered the note above with this source code:

``` markdown
{{{ include <file_to_include>.qmd }}}
```

Also, you need to vary the number of backticks when starting the markdown block compared to the source code you are commenting. I used four ``` in rednering the above source code comment, whereas I only used 3 in the above note

Warning

If I keep exaplaining this in markdown, it will be recursive. Check out the source code on the right sidebar for this (and other) pages if you have not already. This is also partly the reason you can’t self-reference a file and do recursion in quarto.

Note

Note that there are five types of callouts, including: note, warning, important, tip, and caution.

You can also make collabsable sections!