mlr3book

Package to build the mlr3 book using quarto.

Rendered Versions

Clone the mlr-org/mlr3book repository.
Call make install to initialize the renv virtual environment. The file book/renv.lock records all packages needed to build the book.
To build the book, run one of the following commands:
```
# HTML
quarto render book/ --to html

# PDF
quarto render book/ --to pdf
```
These command use the virtual environment created by renv.
If your change to the book requires a new R package, install the package in the renv environment. For this, start an R session in the book/ directory and install the package with renv::install(). Then call renv::snapshot() to update book/renv.lock. Commit book/renv.lock with your changes to a pull request.

Alternatively, you "serve" the book via a local server:

quarto preview book/

The command above starts a service which automatically (re-)compiles the book sources in the background whenever a file is modified.

Alternatively, you can use the provided Makefile (c.f. see make help). This way, you can

The root directory is a regular R package. The book itself is in the subdirectory "book".

For lists please use * and not -.

Chunks are named automatically as [chapter-name]-# by calling name_chunks_mlr3book():

mlr3book::name_chunks_mlr3book()

or alternatively executing make names from the terminal.

You have to options to include a figure:

In the qmd: knitr::include_graphics("Figures/some_figure.svg")
Add book/Figures/some_figure.svg and book/Figures/some_figure.pdf to the repository.

Do not use markdown syntax [](<figure>) to include figures.
Do not include pdf in the qmd: knitr::include_graphics("Figures/some_figure.pdf").

To add a new figure into the repository consider the following rules:

Add the file in the book/images folder without any subdirectory.
Store the original figure as a svg file if possible, i.e. if it is a vector graphic. This allows us to re-use or modify images in the future.
png files should have reasonable resolution, i.e. the width of a pixel graphic should be between 400px and 2000px. If a higher resolution is needed to obtain a readable plot you are probably doing something wrong, e.g. use a pixel graphic where you should use a vector graphic.
Please look at the file size.
- If your pdf or svg file is larger than 1MB it probably contains unnecessary hidden content or unvectorized parts.
- If your png file is larger than 1MB the resolution is probably too big.

How do I convert svg to pdf?
- Use Inkscape or any other tool which does not convert to raster images.
How do I convert pdf to svg?
- Use Inkscape which allows you to also remove unwanted parts of the pdf.
Do not use screenshots!
- Google Slides allows svg export.
- PDF can be converted to svg and you can even cut parts.
- HTML can be converted to svg.
The difference between vector (svg) and pixel (png) graphics should be known.
- Attention: svg and pdf also support to include pixel graphics. There is no guarantee that a svg or pdf is a pure vector graphic. If you paste a pixel graphic (e.g. a screenshot) into Inkscape and save it as svg it does not magically become a vector graphic.