mlr3book

Package to build the mlr3 bookdown book.

Rendered Versions

HTML
PDF

Building the book

To install all necessary dependencies for the book, install this R package using remotes:

remotes::install_github("mlr-org/mlr3book", dependencies = TRUE)

To build the book, run one of the following commands:

# HTML
withr::with_dir("bookdown", bookdown::render_book("index.Rmd",
  output_format = "bookdown::gitbook"))

# PDF
withr::with_dir("bookdown", bookdown::render_book("index.Rmd",
  output_format = "bookdown::pdf_book"))

Serve the book

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

bookdown::serve_book("bookdown")

The command above starts a service which automatically (re-)compiles the bookdown sources in the background whenever a file is modified. If your browser does not open automatically, go to http://127.0.0.1:4321/.

Makefile approach

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

install dependencies
build the HTML book -> make html
build the PDF book (bookdown:pdf_book) -> make pdf

File system structure

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

Style Guide

Lists

For lists please use * and not -.

Chunk Names

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

mlr3book::name_chunks_mlr3book()

or alternatively executing make names from the terminal.

Figures

You have to options to include a figure:

Vector graphic

In the Rmd: knitr::include_graphics("images/some_figure.svg")
Add bookdown/images/some_figure.svg and bookdown/images/some_figure.pdf to the repository.

Pixel graphic

In the Rmd: knitr::include_graphics("images/some_figure.png")
Add only bookdown/images/some_figure.png to the repository.

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

Adding a new figure

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

Add the file in the bookdown/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.

Further aspects

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.

Spacing

Always start a new sentence on a new line, this keeps the diff readable.
Put an empty line before and after code blocks.

muskuloes/mlr3book