From f387f4c1d9d5a2b7b78d454e16a180f49bc63d1c Mon Sep 17 00:00:00 2001 From: mo8it Date: Sat, 17 May 2025 15:49:26 +0200 Subject: [PATCH] Add setup and usage pages --- website/content/_index.md | 134 ++------------------------------- website/content/setup/index.md | 77 +++++++++++++++++++ website/content/usage/index.md | 62 +++++++++++++++ website/templates/index.html | 2 +- website/templates/macros.html | 10 +-- 5 files changed, 150 insertions(+), 135 deletions(-) create mode 100644 website/content/setup/index.md create mode 100644 website/content/usage/index.md diff --git a/website/content/_index.md b/website/content/_index.md index a58f267e..4bb4483b 100644 --- a/website/content/_index.md +++ b/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) 📚️_ - + -## Getting Started - -### 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: +## Quick start ```bash +# Installation cargo install rustlings -``` - -
-If the installation fails… (click to expand) - -- 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) - -
- -### Initialization - -After installing Rustlings, run the following command to initialize the `rustlings/` directory: - -```bash +# Initialization rustlings init -``` - -
-If the command rustlings can't be found… (click to expand) - -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 - -
- -Now, go into the newly initialized directory and launch Rustlings for further instructions on getting started with the exercises: - -```bash -cd rustlings/ +# Moving into new directory +cd rustlings +# Starting 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). - -## Doing exercises - -The exercises are sorted by topic and can be found in the subdirectory `exercises/`. -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. - -
-If detecting file changes in the exercises/ directory fails… (click to expand) - -> 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). - -
- -### 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 -``` +Visit the [**setup**](@/setup/index.md) page for more details 🧰 diff --git a/website/content/setup/index.md b/website/content/setup/index.md new file mode 100644 index 00000000..7e628f8a --- /dev/null +++ b/website/content/setup/index.md @@ -0,0 +1,77 @@ ++++ +title = "Setup" ++++ + + + +## 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 +``` + +
+If the installation fails… (click to expand) + +> - 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) + +
+ +## Initialization + +After installing Rustlings, run the following command to initialize the `rustlings/` directory: + +```bash +rustlings init +``` + +
+If the command rustlings can't be found… (click to expand) + +> 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) + +
+ +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). diff --git a/website/content/usage/index.md b/website/content/usage/index.md new file mode 100644 index 00000000..44e24a22 --- /dev/null +++ b/website/content/usage/index.md @@ -0,0 +1,62 @@ ++++ +title = "Usage" ++++ + + + +## Doing exercises + +The exercises are sorted by topic and can be found in the subdirectory `exercises/`. +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. + +
+If detecting file changes in the exercises/ directory fails… (click to expand) + +> 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). + +
+ +### 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 +``` diff --git a/website/templates/index.html b/website/templates/index.html index 58777651..c61defd3 100644 --- a/website/templates/index.html +++ b/website/templates/index.html @@ -6,6 +6,6 @@

Rustlings

- {{ section.content | replace(from="", to=macros::toc() ) | safe }} + {{ section.content | safe }}
{% endblock %} diff --git a/website/templates/macros.html b/website/templates/macros.html index ce517b0b..dd7b928c 100644 --- a/website/templates/macros.html +++ b/website/templates/macros.html @@ -1,15 +1,9 @@ {% macro toc() %} - {%- if page.toc -%} - {% set_global toc = page.toc %} - {%- else -%} - {% set_global toc = section.toc %} - {%- endif -%} - - {% if toc %} + {% if page.toc %}