Quarto Lecture Notes

04 May 2024 - Andrew Young

Several people have asked me how I prepare my lectures notes in HTML and PDF format. Here’s an overview of my workflow, with a detailed step-by-step guide. This is slightly different to how I do it because I use a “book” project rather than a “website” project, but the principles are the same.

Here’s an example web site.

Here’s a detailed walkthrough:

Set up an empty GitHub repository

I first set up a blank repository on GitHub. Initially this just contains a README.md file and a LICENSE. I have somewhat arbitrarily chosen the MIT license, “A short and simple permissive license with conditions only requiring preservation of copyright and license notices.” Alternatively, you can create the Quarto project then push the whole thing to GitHub – whichever order you find more convenient.

The repository I have created is called andys-quarto-example.

Install Quarto

You need to install Quarto. You can follow these on-line instructions. On my Mac I use Homebrew as a package manager which you can use to install Quarto using brew install --cask quarto.

Set up VS Code

I use Visual Studio Code as an editor. In VS Code you can install a Quarto extension.

Start a new Quarto project

In VS Code you can create a new Quarto project – on the Mac this is shift-command-P, then type “Quarto: Create New Project”, then select “Website Project”. This will create a skeleton project.

However, I find it easier just to add a few files to my repository. I have added the following files:

You can see the content of these files in the GitHub repository.

Publishing the website

You can publish the website following the Quarto GitHub pages instructions.

To do this make some edits to your _quarto.yml file and add an empty .nojekyll file to the root of your project. You can then render the web page in VS Code by selecting “Quarto: Render Website” from the command palette.

Push this to GitHub. On the GitHub web page you can go to the settings page for the repository, select “Pages” from the left hand menu, then choose “Deploy from a branch”, and select “main” “/docs”. That should publish the first version of your website. This is the easiest way. You can set up a GitHub action, which is probably better but I have not done this yet.

This is what I have done to produce the following web page https://phajy.github.io/andys-quarto-example/.

Add some content

I have created an additional page called “Geodesics” and added a link to this in the _quarto.yml file. The content of this page starts off as follows.

## Parallel-transport and geodesics

Here is an excerpt from the GR lecture notes.

![Parallel transport of a vector $\vec{v}(\lambda)$ where $\lambda$ is an affine parameter. For geodesics the vector $\vec{v}$ is a tangent vector, $\vec{u}(\lambda)$.](parallel_transport.png){width=300 #fig-parallel-transport}

We can use the idea of parallel transport to construct *geodesics*, defined as curves that parallel-transport their own tangent vectors. That is, for a geodesic

$$
\begin{aligned}
    \pmb{\nabla}_{\vec u} {\vec u} &= 0 \\
    \text{i.e.} \qquad u^\beta {u^\alpha}_{;\beta} &= 0 \\
    \text{i.e.} \qquad u^\beta {u^\alpha}_{,\beta} +
        {\Gamma^\alpha}_{\beta\gamma} u^\beta u^\gamma &= 0 \\
    \text{or} \qquad \frac{d}{d\lambda} \left( \frac{d x^\alpha}{d\lambda}
        \right) + {\Gamma^\alpha}_{\beta\gamma} \frac{d x^\beta}{d\lambda} \frac{d
        x^\gamma}{d\lambda} &= 0
\end{aligned}
$$

where in the last of these expressions (often called the *geodesic equation*, though the first is also the geodesic equation), $\lambda$ is a continuous parameter along the curve.

A few things to note:

More information in the Quarto documentation.

Questions

I’m sure I’ve left out some top tips / important instructions. Please let me know if you have any questions or suggestions for improvement.