QmdMD

Quarto makes it easy to render scientific posts with Python and R, but for personal websites using a static site generator, such as Jekyll, you need markdown files with a little more markup. This extension does just that! It converts QMD files into Kramdown-compliant markdown files, adds custom YAML metadata, and ensures links, images, and other entities are correctly formatted. With simple configuration options in the qmdmd YAML header field, you can easily modify paths for images and organize figures. Need custom metadata in your markdown front-matter? Populate the output YAML header with additional metadata from the meta YAML header tree of your .qmd document.

Installation

To install this extension in your current directory (or into the Quarto project that you're currently working in), use the following command:

quarto add Khlick/QmdMD

Options {#qmdmd-options}

The qmdMD extension supports customization through the qmdmd section in the YAML header of your Quarto documents. Here are the options you can set:

Option	Description	Default Value
fig-rel	Specifies the relative root for image paths.	"."
fig-root	Specifies an additional root path for images. This can be useful if you want to place all figures in a specific directory.	""

Example YAML Configuration

Here is an example of how to use these options in the YAML header of a Quarto document, ggplot2-demo.qmd:

---
title: ggplot2 demo
author: Khris Griffis, Ph.D.
format: qmdmd-gfm
qmdmd:
  fig-rel: ".."
  fig-root: "assets/figures"
---

## Air Quality

@fig-airquality further explores the impact of temperature on ozone level.

```{r}
#| label: fig-airquality
#| fig-cap: "Temperature and ozone level."
#| warning: false

library(ggplot2)

ggplot(airquality, aes(Temp, Ozone)) + 
  geom_point() + 
  geom_smooth(method = "loess")
```

Example Renders

{width="100%"}

Figure 1. Comparison between Quarto renders from QmdMD (left) and Quarto GFM (right). QmdMD renders a block of YAML front-matter based on the input metadata for further rendering by Kramdown (or other markdown parser) in the GFM style.

Rendering the file to quarto-style markdown with quarto render ggplot2-demo-markdown.md --to markdown yields Quarto's new(er) cell encoding scheme:

[Figure 1](#fig-airquality){.quarto-xref}
further explores the impact of temperature on ozone level.

:::: cell
``` {.r .cell-code}
library(ggplot2)

ggplot(airquality, aes(Temp, Ozone)) + 
  geom_point() + 
  geom_smooth(method = "loess")
```

::: cell-output-display
![](./assets/images/fig-airquality-1.png)
:::
::::

Figure 2. Markdown rendering in Quarto yields Quarto-style cell encodings. These encodings are not compatible with Kramdown or other GFM parsers.

The extension will log any changes made to the figure paths during processing. This ensures you can track the modifications and adjust your project structure accordingly.

Features

Custom YAML front-matter

Custom YAML front-matter may be inserted into the rendered markdown (.md) by utilizing the meta: YAML field in the .qmd file:

meta:
  tags:
    - featured
    - neuroscience
  options:
    - someOption

Which will render at the base level of the output file's YAML front-matter:

tags:
- featured
- neuroscience
options:
- someOption

The .qmd header is expected to have fields author, title, and date, where date is optional as the extension will automatically populate it with the rendered date (formatted as %Y-%m-%d %H:%M:%S %z). Further, the extension appends a new metadata field, generated-on, which has the date of rendering (formmatted as %Y-%m-%d ).

File Management

A major feature of the extension is the ability for the extension to move figure files from their Quarto generated folder to those specified in the QmdMD options. QmdMD will report any changes to file locations in the stdout during render. NOTE: Files in the destination directory are overwritten, so ensure unique names or paths for each figure/QMD file.

Usage

You can either place the format in the QMD file's YAML header:

---
# document metadata
format: qmdmd-gfm
---

Or by using the Quarto --to, -t option for render:

quarto render document.qmd --to qmdMD-gfm

Example

For a complete example, please refer to the template.qmd and its rendered output template.md.

---

Requirements

Only Quarto 1.5.5x or greater is required for the extension. However, to render the template.qmd, you'll also need R and Python available to your quarto installation (see quarto check).

At the time of writing, here's my installation:

Quarto 1.6.1
[>] Checking versions of quarto binary dependencies...
      Pandoc version 3.2.0: OK
      Dart Sass version 1.70.0: OK
      Deno version 1.41.0: OK
      Typst version 0.11.0: OK
[>] Checking versions of quarto dependencies......OK
[>] Checking Quarto installation......OK
      Version: 1.6.1
      Path: ~\AppData\Local\Programs\Quarto\bin
      CodePage: 1252

[>] Checking tools....................OK
      TinyTeX: (not installed)
      Chromium: (not installed)

[>] Checking LaTeX....................OK
      Tex:  (not detected)

[>] Checking basic markdown render....OK

[>] Checking Python 3 installation....OK
      Version: 3.12.1
      Path: ./qmdMD/.python312/Scripts/python.exe
      Jupyter: 5.7.2
      Kernels: python3

[>] Checking Jupyter engine render....OK

[>] Checking R installation...........OK
      Version: 4.2.2
      Path: ~/R/R-42~1.2
      LibPaths:
        - ~/R/win-library/4.2
        - ~/R/R-4.2.2/library
      knitr: 1.45
      rmarkdown: 2.27

[>] Checking Knitr engine render......OK

The template.qmd requires the following R and Python libraries

R Packages

• knitr
• reticulate
• ggplot2
• rmarkdown

Python Packages

• numpy
• matplotlib
• pandas
• jupyter