Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mlr-org/mlr3website
The mlr3 quarto website and accomanying R package.
https://github.com/mlr-org/mlr3website
Last synced: about 2 months ago
JSON representation
The mlr3 quarto website and accomanying R package.
- Host: GitHub
- URL: https://github.com/mlr-org/mlr3website
- Owner: mlr-org
- Created: 2022-02-20T09:33:22.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2024-10-18T11:16:52.000Z (2 months ago)
- Last Synced: 2024-10-19T20:56:56.638Z (2 months ago)
- Language: R
- Homepage: https://mlr-org.com
- Size: 328 MB
- Stars: 8
- Watchers: 7
- Forks: 2
- Open Issues: 15
-
Metadata Files:
- Readme: README.Rmd
Awesome Lists containing this project
README
---
output: github_document
---
# mlr-org Website 
[](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.