toc-title
Table of contents

mkquartodocs

Make gorgeous reproducible documentation with quarto and mkdocs

It is a plugin for mkdocs that renders quarto markdown documents into github, so they are built with the rest of the documentation.

Why?

In many instances the documentation contains runnable code, and it makes sense that you verify that the code runs and keep the output of the code in sync with the current status of the document and software packages involved.

But mainly I really got tired of manually rendering documents and copying outpus.

Usage

1. Install the dependencies: Installation
2. Add the plugin to your configuration: Configuration
3. Add .qmd files to your ./docs/ directoy
4. Run mkdocs build

This will render code chunks and save the outputs! Check out https://quarto.org/ for more examples on how to use the format.

This ....

```{python}
print(1+2)
```

Will become this ...

:::: {.cell execution_count="1"}

print(1+2)

::: {.cell-output .cell-output-stdout} 3 ::: ::::

Installation

1. Make sure you have quarto installed in your computer.

   • https://quarto.org/docs/get-started/

2. Install mkquartodocs

pip install mkquartodocs

Configuration

Add mkquartodocs to your plugins in your mkdocs.yml

# Whatever is in your mkdocs.yml configuration file....
# ...

plugins:
  - mkquartodocs

Available configuration options:

• quarto_path: Specifies where to look for the quarto executable.
• keep_output: If true it will skip the cleanup step in the directory.
• ignore: a python regular expressions that if matched will mark the file to not be rendered. Note that they need to be full matches

# Whatever is in your mkdocs.yml configuration file....
# ...

plugins:
  - mkquartodocs:
      quarto_path: /home/my_folder/some/weird/place/to/have/executables/quarto
      keep_output: true
      ignore: (.*broken.*.qmd)|(.*page[0-9].qmd)

Running

NOTHING !!! you do not have to run it manually!!

When you call mkdocs build, it should automatically find your .qmd files, render them, generate the output and clean after itself.

TODO

The things that need to/could be added to the project:

• quarto project support
• render in temporary directory, posibly with a 'safe' argument
• addition of files not in the docs directory, 'include' argument
• add readme to testing data
• move INFO - mkquartodocs: Running RemoveCellDataPreprocessor to debug log