-
-
Notifications
You must be signed in to change notification settings - Fork 2
/
README.Rmd
92 lines (63 loc) · 3.36 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
---
output: github_document
---
# mlr-org Website <img src="man/figures/logo.png" align="right" width = "120" />
[](https://github.com/mlr-org/mlr3website/actions/workflows/build-website.yml)
# 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.
1. Call `renv::restore(project = "mlr-org/")` to download and install all required packages.
1. Run the following command from your terminal to preview the website:
```bash
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](https://www.r-bloggers.com/).
**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](https://bootswatch.com/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}`.
1. Start with a new `index.qmd` file and write your post.
1. Use only one sentence for the description and start with a verb.
Do not repeat the title.
See the previously published articles for examples.
1. 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.
1. Call `renv::snapshot()` to record the package in `renv.lock`.
1. 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](https://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.