Merge pull request #2247 from rust-lang/website

Website

4 files changed, 227 insertions, 0 deletions

diff --git a/website/content/_index.md b/website/content/_index.md
new file mode 100644
index 0000000..4bb4483
--- /dev/null
+++ b/website/content/_index.md
@@ -0,0 +1,21 @@
++++
++++
+
+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) 📚️_
+
+<script src="https://asciinema.org/a/719805.js" id="asciicast-719805" async="true"></script>
+
+## Quick start
+
+```bash
+# Installation
+cargo install rustlings
+# Initialization
+rustlings init
+# Moving into new directory
+cd rustlings
+# Starting Rustlings
+rustlings
+```
+
+Visit the [**setup**](@/setup/index.md) page for more details 🧰
diff --git a/website/content/community-exercises/index.md b/website/content/community-exercises/index.md
new file mode 100644
index 0000000..0f713d7
--- /dev/null
+++ b/website/content/community-exercises/index.md
@@ -0,0 +1,73 @@
++++
+title = "Community Exercises"
++++
+
+## List of Community Exercises
+
+- 🇯🇵 [Japanese Rustlings](https://github.com/sotanengel/rustlings-jp)：A Japanese translation of the Rustlings exercises.
+- 🇨🇳 [Simplified Chinese Rustlings](https://github.com/SandmeyerX/rustlings-zh-cn): A simplified Chinese translation of the Rustlings exercises.
+
+> You can use the same `rustlings` program that you installed with `cargo install rustlings` to run community exercises.
+
+## Creating Community Exercises
+
+Rustling's support for community exercises allows you to create your own exercises to focus on some specific topic.
+You could also offer a translation of the original Rustlings exercises as community exercises.
+
+### Getting Started
+
+To create community exercises, install Rustlings and run `rustlings dev new PROJECT_NAME`.
+This command will, similar to `cargo new PROJECT_NAME`, create the template directory `PROJECT_NAME` with all what you need to get started.
+
+_Read the comments_ in the generated `info.toml` file to understand its format.
+It allows you to set a custom welcome and final message and specify the metadata of every exercise.
+
+### Creating an Exercise
+
+Here is an example of the metadata of one exercise:
+
+```toml
+[[exercises]]
+name = "intro1"
+hint = """
+To finish this exercise, you need to …
+These links might help you …"""
+```
+
+After entering this in `info.toml`, create the file `intro1.rs` in the `exercises/` directory.
+The exercise needs to contain a `main` function, but it can be empty.
+Adding tests is recommended.
+Look at the official Rustlings exercises for inspiration.
+
+You can optionally add a solution file `intro1.rs` to the `solutions/` directory.
+
+Now, run `rustlings dev check`.
+It will tell you about any issues with your exercises.
+For example, it will tell you to run `rustlings dev update` to update the `Cargo.toml` file to include the new exercise `intro1`.
+
+`rustlings dev check` will also run your solutions (if you have any) to make sure that they run successfully.
+
+That's it!
+You finished your first exercise 🎉
+
+### Cargo.toml
+
+Except of the `bin` list, you can modify the `Cargo.toml` file as you want.
+
+> The `bin` list is automatically updated by running `rustlings dev update`
+
+- You can add dependencies in the `[dependencies]` table.
+- You might want to [configure some lints](https://doc.rust-lang.org/cargo/reference/manifest.html#the-lints-section) for all exercises. You can do so in the `[lints.rust]` and `[lints.clippy]` tables.
+
+### Publishing
+
+Now, add more exercises and publish them as a Git repository.
+
+Users just have to clone that repository and run `rustlings` in it to start working on your exercises (just like the official ones).
+
+One difference to the official exercises is that the solution files will not be hidden until the user finishes an exercise.
+But you can trust your users to not open the solution too early 😉
+
+### Sharing
+
+After publishing your community exercises, open an issue or a pull request in the [official Rustlings repository](https://github.com/rust-lang/rustlings) to add your project to the [list of community exercises](#list-of-community-exercises) 😃
diff --git a/website/content/setup/index.md b/website/content/setup/index.md
new file mode 100644
index 0000000..54551ad
--- /dev/null
+++ b/website/content/setup/index.md
@@ -0,0 +1,78 @@
++++
+title = "Setup"
++++
+
+<!-- toc -->
+
+## Installing Rust
+
+Before installing Rustlings, you must have the **latest version of Rust** installed.
+Visit [www.rust-lang.org/tools/install](https://www.rust-lang.org/tools/install) for further instructions.
+This will also install _Cargo_, Rust's package/project manager.
+
+> 🐧 If you are on **Linux**, make sure you have `gcc` installed (_for a linker_).
+>
+> Debian: `sudo apt install gcc`\
+> Fedora: `sudo dnf install gcc`
+
+> 🍎 If you are on **MacOS**, make sure you have _Xcode and its developer tools_ installed: `xcode-select --install`
+
+## Installing Rustlings
+
+The following command will download and compile Rustlings:
+
+```bash
+cargo install rustlings
+```
+
+{% details(summary="If the installation fails…") %}
+
+- 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)
+
+{% end %}
+
+## Initialization
+
+After installing Rustlings, run the following command to initialize the `rustlings/` directory:
+
+```bash
+rustlings init
+```
+
+{% details(summary="If the command <code>rustlings</code> can't be found…") %}
+
+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)
+
+{% end %}
+
+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).
+
+## Usage
+
+After being done with the setup, visit the [**usage**](@/usage/index.md) page for some info about using Rustlings 🚀
diff --git a/website/content/usage/index.md b/website/content/usage/index.md
new file mode 100644
index 0000000..88dabf4
--- /dev/null
+++ b/website/content/usage/index.md
@@ -0,0 +1,55 @@
++++
+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="If detecting file changes in the <code>exercises/</code> directory fails…") %}
+
+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 a virtual machine (e.g. WSL).
+
+{% end %}
+
+## 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_ discussions](https://github.com/rust-lang/rustlings/discussions/categories/q-a?discussions_q=) if your question isn't answered there 💡
+
+## 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.
+
+> If you want to create your own Rustlings exercises, visit the [**community exercises**](@/community-exercises/index.md) page 🏗️