Add setup and usage pages

website/content/_index.md

@@ -3,137 +3,19 @@
 
 Small exercises to get you used to reading and writing [Rust](https://www.rust-lang.org) code - _Recommended in parallel to reading [the official Rust book](https://doc.rust-lang.org/book) 📚️_
 
-<!-- toc -->
+<script src="https://asciinema.org/a/719805.js" id="asciicast-719805" async="true"></script>
 
-## Getting Started
+## Quick start
-
-### Installing Rust
-
-Before installing Rustlings, you need to have the **latest version of Rust** installed.
-Visit [www.rust-lang.org/tools/install](https://www.rust-lang.org/tools/install) for further instructions on installing Rust.
-This will also install _Cargo_, Rust's package/project manager.
-
-> 🐧 If you are on Linux, make sure you have installed `gcc` (for a linker).
->
-> Deb: `sudo apt install gcc`
->
-> Dnf: `sudo dnf install gcc`
-
-> 🍎 If you are on MacOS, make sure you have installed Xcode and its developer tools by running `xcode-select --install`.
-
-### Installing Rustlings
-
-The following command will download and compile Rustlings:
 
 ```bash
+# Installation
 cargo install rustlings
-```
+# Initialization
-
-<details>
-<summary><strong>If the installation fails…</strong> (<em>click to expand</em>)</summary>
-
-- Make sure you have the latest Rust version by running `rustup update`
-- Try adding the `--locked` flag: `cargo install rustlings --locked`
-- Otherwise, please [report the issue](https://github.com/rust-lang/rustlings/issues/new)
-
-</details>
-
-### Initialization
-
-After installing Rustlings, run the following command to initialize the `rustlings/` directory:
-
-```bash
 rustlings init
-```
+# Moving into new directory
-
+cd rustlings
-<details>
+# Starting Rustlings
-<summary><strong>If the command <code>rustlings</code> can't be found…</strong> (<em>click to expand</em>)</summary>
-
-You are probably using Linux and installed Rust using your package manager.
-
-Cargo installs binaries to the directory `~/.cargo/bin`.
-Sadly, package managers often don't add `~/.cargo/bin` to your `PATH` environment variable.
-
-The solution is to …
-
-- either add `~/.cargo/bin` manually to `PATH`
-- or to uninstall Rust from the package manager and install it using the official way with `rustup`: https://www.rust-lang.org/tools/install
-
-</details>
-
-Now, go into the newly initialized directory and launch Rustlings for further instructions on getting started with the exercises:
-
-```bash
-cd rustlings/
 rustlings
 ```
 
-## Working environment
+Visit the [**setup**](@/setup/index.md) page for more details 🧰
-
-### Editor
-
-Our general recommendation is [VS Code](https://code.visualstudio.com/) with the [rust-analyzer plugin](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer).
-But any editor that supports [rust-analyzer](https://rust-analyzer.github.io/) should be enough for working on the exercises.
-
-### Terminal
-
-While working with Rustlings, please use a modern terminal for the best user experience.
-The default terminal on Linux and Mac should be sufficient.
-On Windows, we recommend the [Windows Terminal](https://aka.ms/terminal).
-
-## Doing exercises
-
-The exercises are sorted by topic and can be found in the subdirectory `exercises/<topic>`.
-For every topic, there is an additional `README.md` file with some resources to get you started on the topic.
-We highly recommend that you have a look at them before you start 📚️
-
-Most exercises contain an error that keeps them from compiling, and it's up to you to fix it!
-Some exercises contain tests that need to pass for the exercise to be done ✅
-
-Search for `TODO` and `todo!()` to find out what you need to change.
-Ask for hints by entering `h` in the _watch mode_ 💡
-
-### Watch Mode
-
-After the [initialization](#initialization), Rustlings can be launched by simply running the command `rustlings`.
-
-This will start the _watch mode_ which walks you through the exercises in a predefined order (what we think is best for newcomers).
-It will rerun the current exercise automatically every time you change the exercise's file in the `exercises/` directory.
-
-<details>
-<summary><strong>If detecting file changes in the <code>exercises/</code> directory fails…</strong> (<em>click to expand</em>)</summary>
-
-> You can add the **`--manual-run`** flag (`rustlings --manual-run`) to manually rerun the current exercise by entering `r` in the watch mode.
->
-> Please [report the issue](https://github.com/rust-lang/rustlings/issues/new) with some information about your operating system and whether you run Rustlings in a container or virtual machine (e.g. WSL).
-
-</details>
-
-### Exercise List
-
-In the [watch mode](#watch-mode) (after launching `rustlings`), you can enter `l` to open the interactive exercise list.
-
-The list allows you to…
-
-- See the status of all exercises (done or pending)
-- `c`: Continue at another exercise (temporarily skip some exercises or go back to a previous one)
-- `r`: Reset status and file of the selected exercise (you need to _reload/reopen_ its file in your editor afterwards)
-
-See the footer of the list for all possible keys.
-
-## Questions?
-
-If you need any help while doing the exercises and the builtin-hints aren't helpful, feel free to ask in the [_Q&A_ category of the discussions](https://github.com/rust-lang/rustlings/discussions/categories/q-a?discussions_q=) if your question wasn't asked yet 💡
-
-## Continuing On
-
-Once you've completed Rustlings, put your new knowledge to good use!
-Continue practicing your Rust skills by building your own projects, contributing to Rustlings, or finding other open-source projects to contribute to.
-
-## Uninstalling Rustlings
-
-If you want to remove Rustlings from your system, run the following command:
-
-```bash
-cargo uninstall rustlings
-```

website/content/setup/index.md

@@ -0,0 +1,77 @@
++++
+title = "Setup"
++++
+
+<!-- toc -->
+
+## Installing Rust
+
+Before installing Rustlings, you need to have the **latest version of Rust** installed.
+Visit [www.rust-lang.org/tools/install](https://www.rust-lang.org/tools/install) for further instructions on installing Rust.
+This will also install _Cargo_, Rust's package/project manager.
+
+> 🐧 If you are on Linux, make sure you have installed `gcc` (for a linker).
+>
+> Deb: `sudo apt install gcc`
+>
+> Dnf: `sudo dnf install gcc`
+
+> 🍎 If you are on MacOS, make sure you have installed Xcode and its developer tools by running `xcode-select --install`.
+
+## Installing Rustlings
+
+The following command will download and compile Rustlings:
+
+```bash
+cargo install rustlings
+```
+
+<details>
+<summary><strong>If the installation fails…</strong> (<em>click to expand</em>)</summary>
+
+> - Make sure you have the latest Rust version by running `rustup update`
+> - Try adding the `--locked` flag: `cargo install rustlings --locked`
+> - Otherwise, please [report the issue](https://github.com/rust-lang/rustlings/issues/new)
+
+</details>
+
+## Initialization
+
+After installing Rustlings, run the following command to initialize the `rustlings/` directory:
+
+```bash
+rustlings init
+```
+
+<details>
+<summary><strong>If the command <code>rustlings</code> can't be found…</strong> (<em>click to expand</em>)</summary>
+
+> You are probably using Linux and installed Rust using your package manager.
+>
+> Cargo installs binaries to the directory `~/.cargo/bin`.
+> Sadly, package managers often don't add `~/.cargo/bin` to your `PATH` environment variable.
+>
+> - Either add `~/.cargo/bin` manually to `PATH`
+> - Or uninstall Rust from the package manager and [install it using the official way with `rustup`](https://www.rust-lang.org/tools/install)
+
+</details>
+
+Now, go into the newly initialized directory and launch Rustlings for further instructions on getting started with the exercises:
+
+```bash
+cd rustlings/
+rustlings
+```
+
+## Working environment
+
+### Editor
+
+Our general recommendation is [VS Code](https://code.visualstudio.com/) with the [rust-analyzer plugin](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer).
+But any editor that supports [rust-analyzer](https://rust-analyzer.github.io/) should be enough for working on the exercises.
+
+### Terminal
+
+While working with Rustlings, please use a modern terminal for the best user experience.
+The default terminal on Linux and Mac should be sufficient.
+On Windows, we recommend the [Windows Terminal](https://aka.ms/terminal).

website/content/usage/index.md

@@ -0,0 +1,62 @@
++++
+title = "Usage"
++++
+
+<!-- toc -->
+
+## Doing exercises
+
+The exercises are sorted by topic and can be found in the subdirectory `exercises/<topic>`.
+For every topic, there is an additional `README.md` file with some resources to get you started on the topic.
+We highly recommend that you have a look at them before you start 📚️
+
+Most exercises contain an error that keeps them from compiling, and it's up to you to fix it!
+Some exercises contain tests that need to pass for the exercise to be done ✅
+
+Search for `TODO` and `todo!()` to find out what you need to change.
+Ask for hints by entering `h` in the _watch mode_ 💡
+
+### Watch Mode
+
+After the [initialization](@/setup/index.md#initialization), Rustlings can be launched by simply running the command `rustlings`.
+
+This will start the _watch mode_ which walks you through the exercises in a predefined order (what we think is best for newcomers).
+It will rerun the current exercise automatically every time you change the exercise's file in the `exercises/` directory.
+
+<details>
+<summary><strong>If detecting file changes in the <code>exercises/</code> directory fails…</strong> (<em>click to expand</em>)</summary>
+
+> You can add the **`--manual-run`** flag (`rustlings --manual-run`) to manually rerun the current exercise by entering `r` in the watch mode.
+>
+> Please [report the issue](https://github.com/rust-lang/rustlings/issues/new) with some information about your operating system and whether you run Rustlings in a container or virtual machine (e.g. WSL).
+
+</details>
+
+### Exercise List
+
+In the [watch mode](#watch-mode) (after launching `rustlings`), you can enter `l` to open the interactive exercise list.
+
+The list allows you to…
+
+- See the status of all exercises (done or pending)
+- `c`: Continue at another exercise (temporarily skip some exercises or go back to a previous one)
+- `r`: Reset status and file of the selected exercise (you need to _reload/reopen_ its file in your editor afterwards)
+
+See the footer of the list for all possible keys.
+
+## Questions?
+
+If you need any help while doing the exercises and the builtin-hints aren't helpful, feel free to ask in the [_Q&A_ category of the discussions](https://github.com/rust-lang/rustlings/discussions/categories/q-a?discussions_q=) if your question wasn't asked yet 💡
+
+## Continuing On
+
+Once you've completed Rustlings, put your new knowledge to good use!
+Continue practicing your Rust skills by building your own projects, contributing to Rustlings, or finding other open-source projects to contribute to.
+
+## Uninstalling Rustlings
+
+If you want to remove Rustlings from your system, run the following command:
+
+```bash
+cargo uninstall rustlings
+```

website/templates/index.html

@@ -6,6 +6,6 @@
     <div class="m-3">
         <h1>Rustlings</h1>
 
-        {{ section.content | replace(from="<!-- toc -->", to=macros::toc() ) | safe }}
+        {{ section.content | safe }}
     </div>
 {% endblock %}

website/templates/macros.html

@@ -1,15 +1,9 @@
 {% macro toc() %}
-    {%- if page.toc -%}
+    {% if page.toc %}
-        {% set_global toc = page.toc %}
-    {%- else -%}
-        {% set_global toc = section.toc %}
-    {%- endif -%}
-
-    {% if toc %}
         <div class="px-4 py-0.5 my-3 border-s-4 rounded-xl border-double">
             <nav>
                 <ul class="ml-0 list-none">
-                    {% for parent in toc %}
+                    {% for parent in page.toc %}
                         {% if parent.level == 2 %}
                             <li>
                                 {#- -#}