mlr-org Website

Project Structure

• mlr3website - The root directory contains the mlr3website R package.
• mlr-org/ - Quarto project.
• mlr-org/gallery - Gallery posts.
• .github/workflows Contains workflows to build the website and render gallery posts

Setup

The website is rendered in a virtual environment. The renv package is used to manage the virtual environment. This ensures that we all edit the website with the same package versions.

1. Clone the mlr-org/mlr3website repository.
2. Call renv::restore(project = "mlr-org/") to download and install all required packages.
3. Run the following command from your terminal to preview the website:

quarto preview mlr-org/

Notes

Freeze

The gallery posts are frozen i.e. the documents are not re-rendered during a global project render. Calling quarto preview mlr-org/ or quarto render mlr-org/ will not render the gallery posts again. Calling quarto render on a single file or subdirectory will re-render the single file or all files in the subdirectory.

RSS

The rss feed of the gallery is published on R-bloggers.

CSS

The global css rules are stored in mlr-og/custom.scss. When editing the file, try to stick to the BEM naming pattern and use SASS. We use the Bootswatch Yeti theme. A few style options are specified in mlr-org/_quarto.yml in the Theme section.

How to Add a Gallery Post

The gallery is divided into four broad categories basic, optimization, pipelines and technical. The posts are stored in the corresponding subdirectories in mlr-org/gallery. If you write a series, add it to the series directory.

1. Create a subdirectory in mlr-org/gallery/{category}.
2. Start with a new index.qmd file and write your post.
3. Use only one sentence for the description and start with a verb. Do not repeat the title. See the previously published articles for examples.
4. Render the post with quarto render mlr-org/gallery/{category}/{post}/index.qmd.

Because the gallery posts are not rendered in the CI, you need to ensure that the rendered file is contained in the mlr-org/_freeze subdirectory.

If your post needs a new package or package version:

1. Install the package with renv::install() in the virtual environment.
2. Call renv::snapshot() to record the package in renv.lock.
3. Commit renv.lock with the new post.

How to Change the Website

Pages are .qmd files located in the mlr-org/ directory (e.g. packages.Rmd). See quarto.org to learn more about Quarto.

Workflows

build-website.yml

Builds website. On main, the website is pushed to gh-pages branch. On pull request, the website is previewed with Netlify. The gallery is frozen. Note that this does not use the renv file but instead uses only the dependencies from the mlr3website package. This e.g. ensures that the overview lists are up to date.

gallery-weekly.yml

The workflow restores the renv virtual environment and updates all packages. Then all gallery posts are re-rerendered. Runs once a week.