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.
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.
.qmd
files to your ./docs/
directoymkdocs 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+1)
Will become this …
``` python
print(1+1)
2
Make sure you have quarto installed in your computer.
Install mkquartodocs
pip install mkquartodocs
Add mkquartodocs
to your plugins in your mkdocs.yml
# Whatever is in your mkdocs.yml configuration file....
# ...
plugins:
- mkquartodocs
Available configuration options:
# 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)
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.
The things that need to/could be added to the project: