Bedrock ❤️ Quarto

Why I chose Quarto for building this website.
quarto
Author

Joost Gevaert

Published

August 18, 2024

Modified

August 22, 2023

Quarto makes it really easy to set up a smoothly working and beautiful website. It took me less than 3 days to set up Bedrock’s website with:

  1. custom Home landing page,

  2. a methodology for efficiently creating feature-rich Documentation,

  3. “blog” under Articles,

  4. Community page,

  5. Help ▼ menu,

  6. About page,

  7. and GitHub links to:

    • Bedrock’s home on GitHub (NavBar & Footer),
    • Page specific “View source”, “Edit this page”, “Report an issue” GitHub links (Right SideBar) for documentation pages and articles, to make it as easy as possible for people to contribute to Bedrock’s documentation or correct spelling mistakes in this article 😁.

Quarto makes it easy to implement many features that are essential for modern (docs) websites, see below 🤩. Building all these features from without handy tooling is, … daunting.

Other tools I looked at:

Quarto?

Nice intro, but … Quarto?

  • What
  • How: pandoc
  • Why
  • Who: Posix + Community
  • When

Markdown

Markdown is an easy to read and write text format:

  • It’s plain text so works well with version control
  • It can be rendered into HTML (this website), PDF, Word (.docx), PowerPoint (.pptx) presentation and more…
  • Many very useful basic features, see below.
  • Learn more at: https://quarto.org/docs/authoring/

Equations

Use LaTeX to write equations: \[ x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a} \tag{1}\]

Source Code

See Static Code, Computed Code & Interactive Docs below.

Lists

Quarto’s docs list some pretty awesome lists that I wasn’t aware of, and creative ways of using them. My highlight, definitions:

term or symbol, e.g. \(\alpha\)
definition

Footnotes

Footnotes in a Quarto website get a hover preview 🤩1

“Raw Content”

A somewhat cryptic way of saying that you can use this to to say that this is how you can embed other websites . For example:

```{=html}
<iframe title="Kai Tak - Speckle" src="https://app.speckle.systems/projects/013aaf06e7/models/0fa0287ba8,a739490298,c59c767566#embed=%7B%22isEnabled%22%3Atrue%7D" width="100%" height="500" frameborder="0"></iframe>
```

embeds ⬇️

Static Code, Computed Code & Interactivity

A Quarto Website project produces HTML documents (see _site directory) as output from the Quarto (.qmd), Markdown (.md), or Jupyter Notebook (.ipynb) files, which are then put together into a website with all the features a modern (docs) site needs by Quarto. Code blocks in these HTML documents comes in 2 types:

  1. Static Code. Static code is not executed by Quarto when the website is generated, and can therefore not produce output such as figures. Static code blocks can be generated like this:

      ```{.python}
  print("This is a static code block. The code in this block will not be executed.")
  ```

    Result 👇

print("This is a static code block. The code in this block will not be executed.")

  1. Computed Code. Computed code is executed by Quarto when the website it generated, and can therefore produce output such as figures. These figures can also be made interactive when you use a library such as plotly. Computed code blocks can be generated like this:

      ```{python}
  print("This is a computed code block. The code block will be executed.")
  ```

    Result 👇

Code 
print("This is a computed code block. The code block will be executed.")
This is a computed code block. The code block will be executed.

As you can see, this is a bit tricky, because the difference between a code block being static ({.python}) and computed ({python}) is only a single “.”.

Below a little more exciting example of a computed Python code block. Figure 1 actually comes from Quarto’s Get Started Guide.

Code 
import numpy as np
import matplotlib.pyplot as plt

r = np.arange(0, 2, 0.01)
theta = 2 * np.pi * r
fig, ax = plt.subplots(
  subplot_kw = {'projection': 'polar'} 
)
ax.plot(theta, r)
ax.set_rticks([0.5, 1, 1.5, 2])
ax.grid(True)
plt.show()
Figure 1: A line plot on a polar axis

Code Annotations

Quarto also has beatiful code annotations:

{
  "location": {
    "attributes": {},
    "geometry": "Point / 3D LineString",
    "children": {}
  }
}
1
The geometry of a borehole location is best represented by a “3D LineString”. However, when visualizing the locations for which GI data is available on a 2D map, vertical lines vanish, in such cases using “Point” geometry for the GI location is better.

Awesome Features for Modern Websites

So, Markdown provides a great developer i.e. contributor experience, and the Code & Interactivity features make Quarto documentation useful and engaging, but that doesn’t give you a good website yet. Therefore, this section highlights some of the awesome Quarto features that are essential for modern (docs) websites.

Website Navigation

Warning 1: 🐞 No Search Placeholder

When editing the search appearance when using a search textbox, the “Search” placeholder is not showing up in the website.

Cross-References with Hover Preview

The way that cross-referencing is implemented in Quarto is very slick as well:

Promising Features

Several other Quarto features that I like and (might) want to make use of in the future:

Footnotes

  1. Hey, that tickles 🤣↩︎