feat: reorganizing docs to fit diataxis framework (#3711)

# Description One of DevRel goals was to slowly start designing our docs process, and specially adopting the Diátaxis framework. A quick picture should make it easy to understand what exactly is Diátaxias: ![diataxis](https://diataxis.fr/_images/diataxis.png) Relevant WIP docs for this are (internal links): - [docs philosophy](https://hackmd.io/0ffxsnAARZaaiygZD_kWEA) - [Noir docs 2.0](https://hackmd.io/IdN1KMjIR3CgKk4t0A6-ug) This PR is a first step towards that reorg, by essentially moving things around. There are little changes to the content itself for now. However, during the reorg process, an opportunity came to upgrade to Docusaurus v3.0 with very little overhead, so I took it. ## Problem\* A small retro was made as part of the above [Noir Docs 2.0](https://hackmd.io/IdN1KMjIR3CgKk4t0A6-ug) exercise. ## Summary\* The Diátaxis framework divides docs neatly into four sections. However, in this case, it was deemed important to give a quick reference, so as to tackle the initial interest and motivation of readers and tinkerers. So, five top-level sections: - Getting Started -> Has a quick reference for all of the other sections, by providing a guide, a tutorial, an explanation, and a small reference to other tools. The idea is that most user journeys will eventually start here. - "The Noir Language" -> One of the biggest tasks will be to neatly separate explanations from reference material. This is a task that will be done later on. So this section contains a hybrid. - How-To Guides -> Given the clear distinction between "How-To" and "Tutorial", which is important to keep, this section currently doesn't have any more than the potentially outdated Merkle Tree example. - Tutorials -> Again, since no content was added, only the NoirJS e2e example is in this section. - Reference -> The reference material for Nargo commands and NoirJS lives here. This will be gradually expanded to fit the reference in the Language section.
noir-lang · Dec 11, 2023 · 54a1ed5 · 54a1ed5
1 parent 0a23d42
commit 54a1ed5
Show file tree

Hide file tree

Showing 142 changed files with 4,441 additions and 1,431 deletions.
diff --git a/docs/.eslintignore b/docs/.eslintignore
@@ -0,0 +1,2 @@
+node_modules
+build
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -7,7 +7,7 @@
 # Generated files
 .docusaurus
 .cache-loader
-/docs/docs/noir_js/reference/
+/docs/docs/reference/NoirJS
 
 # Misc
 .DS_Store

diff --git a/docs/babel.config.js b/docs/babel.config.js
diff --git a/...language_concepts/data_types/00_fields.md → ...ations/00_noir/00_data_types/00_fields.md b/...language_concepts/data_types/00_fields.md → ...ations/00_noir/00_data_types/00_fields.md
@@ -158,7 +158,7 @@ fn main() {
 
 ### sgn0
 
-Parity of (prime) Field element, i.e. sgn0(x mod p) = 0 if x ∈ {0, ..., p-1} is even, otherwise sgn0(x mod p) = 1.
+Parity of (prime) Field element, i.e. sgn0(x mod p) = 0 if x ∈ \{0, ..., p-1\} is even, otherwise sgn0(x mod p) = 1.
 
 ```rust
 fn sgn0(self) -> u1

diff --git a/...nguage_concepts/data_types/01_integers.md → ...ions/00_noir/00_data_types/01_integers.md b/...nguage_concepts/data_types/01_integers.md → ...ions/00_noir/00_data_types/01_integers.md
diff --git a/...nguage_concepts/data_types/02_booleans.md → ...ions/00_noir/00_data_types/02_booleans.md b/...nguage_concepts/data_types/02_booleans.md → ...ions/00_noir/00_data_types/02_booleans.md
diff --git a/...anguage_concepts/data_types/03_strings.md → ...tions/00_noir/00_data_types/03_strings.md b/...anguage_concepts/data_types/03_strings.md → ...tions/00_noir/00_data_types/03_strings.md
diff --git a/...language_concepts/data_types/04_arrays.md → ...ations/00_noir/00_data_types/04_arrays.md b/...language_concepts/data_types/04_arrays.md → ...ations/00_noir/00_data_types/04_arrays.md
diff --git a/...anguage_concepts/data_types/05_slices.mdx → ...tions/00_noir/00_data_types/05_slices.mdx b/...anguage_concepts/data_types/05_slices.mdx → ...tions/00_noir/00_data_types/05_slices.mdx
diff --git a/...nguage_concepts/data_types/06_vectors.mdx → ...ions/00_noir/00_data_types/06_vectors.mdx b/...nguage_concepts/data_types/06_vectors.mdx → ...ions/00_noir/00_data_types/06_vectors.mdx
diff --git a/...language_concepts/data_types/07_tuples.md → ...ations/00_noir/00_data_types/07_tuples.md b/...language_concepts/data_types/07_tuples.md → ...ations/00_noir/00_data_types/07_tuples.md
diff --git a/...anguage_concepts/data_types/08_structs.md → ...tions/00_noir/00_data_types/08_structs.md b/...anguage_concepts/data_types/08_structs.md → ...tions/00_noir/00_data_types/08_structs.md
diff --git a/...uage_concepts/data_types/09_references.md → ...ns/00_noir/00_data_types/09_references.md b/...uage_concepts/data_types/09_references.md → ...ns/00_noir/00_data_types/09_references.md
diff --git a/..._concepts/data_types/10_function_types.md → ...0_noir/00_data_types/10_function_types.md b/..._concepts/data_types/10_function_types.md → ...0_noir/00_data_types/10_function_types.md
diff --git a/docs/docs/language_concepts/data_types.md → ...planations/00_noir/00_data_types/index.md b/docs/docs/language_concepts/data_types.md → ...planations/00_noir/00_data_types/index.md
@@ -79,7 +79,7 @@ fn main() {
 }
 ```
 
-Type aliases can also be used with [generics](./06_generics.md):
+Type aliases can also be used with [generics](@site/docs/explanations/00_noir/06_generics.md):
 
 ```rust
 type Id<Size> = Size;

diff --git a/docs/docs/language_concepts/01_functions.md → ...docs/explanations/00_noir/01_functions.md b/docs/docs/language_concepts/01_functions.md → ...docs/explanations/00_noir/01_functions.md
@@ -14,7 +14,7 @@ To declare a function the `fn` keyword is used.
 fn foo() {}
 ```
 
-By default, functions are visible only within the package they are defined. To make them visible outside of that package (for example, as part of a [library](../modules_packages_crates/crates_and_packages.md#libraries)), you should mark them as `pub`:
+By default, functions are visible only within the package they are defined. To make them visible outside of that package (for example, as part of a [library](@site/docs/explanations/02_modules_packages_crates/crates_and_packages.md#libraries)), you should mark them as `pub`:
 
 ```rust
 pub fn foo() {}
@@ -61,7 +61,7 @@ fn main(x : [Field]) // can't compile, has variable size
 fn main(....// i think you got it by now
 ```
 
-Keep in mind [tests](../nargo/02_testing.md) don't differentiate between `main` and any other function. The following snippet passes tests, but won't compile or prove:
+Keep in mind [tests](@site/docs/getting_started/03_tooling/01_testing.md) don't differentiate between `main` and any other function. The following snippet passes tests, but won't compile or prove:
 
 ```rust
 fn main(x : [Field]) {
@@ -188,8 +188,8 @@ Supported attributes include:
 - **builtin**: the function is implemented by the compiler, for efficiency purposes.
 - **deprecated**: mark the function as _deprecated_. Calling the function will generate a warning: `warning: use of deprecated function`
 - **field**: Used to enable conditional compilation of code depending on the field size. See below for more details
-- **oracle**: mark the function as _oracle_; meaning it is an external unconstrained function, implemented in noir_js. See [Unconstrained](./05_unconstrained.md) and [NoirJS](../noir_js/noir_js.md) for more details.
-- **test**: mark the function as unit tests. See [Tests](../nargo/02_testing.md) for more details
+- **oracle**: mark the function as _oracle_; meaning it is an external unconstrained function, implemented in noir_js. See [Unconstrained](./05_unconstrained.md) and [NoirJS](@site/docs/reference/NoirJS/noir_js/index.md) for more details.
+- **test**: mark the function as unit tests. See [Tests](@site/docs/getting_started/03_tooling/01_testing.md) for more details
 
 ### Field Attribute
 

diff --git a/...docs/language_concepts/02_control_flow.md → ...s/explanations/00_noir/02_control_flow.md b/...docs/language_concepts/02_control_flow.md → ...s/explanations/00_noir/02_control_flow.md
diff --git a/docs/docs/language_concepts/03_ops.md → docs/docs/explanations/00_noir/03_ops.md b/docs/docs/language_concepts/03_ops.md → docs/docs/explanations/00_noir/03_ops.md
@@ -29,11 +29,11 @@ keywords:
 | ^         |              XOR two private input types together              |                  Types must be integer |
 | &         |              AND two private input types together              |                  Types must be integer |
 | \|        |              OR two private input types together               |                  Types must be integer |
-| <<        |        Left shift an integer by another integer amount         |                  Types must be integer |
+| \<\<        |        Left shift an integer by another integer amount         |                  Types must be integer |
 | >>        |        Right shift an integer by another integer amount        |                  Types must be integer |
 | !         |                     Bitwise not of a value                     |        Type must be integer or boolean |
-| <         |       returns a bool if one value is less than the other       | Upper bound must have a known bit size |
-| <=        | returns a bool if one value is less than or equal to the other | Upper bound must have a known bit size |
+| \<         |       returns a bool if one value is less than the other       | Upper bound must have a known bit size |
+| \<=        | returns a bool if one value is less than or equal to the other | Upper bound must have a known bit size |
 | >         |       returns a bool if one value is more than the other       | Upper bound must have a known bit size |
 | >=        | returns a bool if one value is more than or equal to the other | Upper bound must have a known bit size |
 | ==        |       returns a bool if one value is equal to the other        |       Both types must not be constants |

diff --git a/docs/docs/language_concepts/04_assert.md → docs/docs/explanations/00_noir/04_assert.md b/docs/docs/language_concepts/04_assert.md → docs/docs/explanations/00_noir/04_assert.md
diff --git a/...ocs/language_concepts/05_unconstrained.md → .../explanations/00_noir/05_unconstrained.md b/...ocs/language_concepts/05_unconstrained.md → .../explanations/00_noir/05_unconstrained.md
diff --git a/docs/docs/language_concepts/06_generics.md → .../docs/explanations/00_noir/06_generics.md b/docs/docs/language_concepts/06_generics.md → .../docs/explanations/00_noir/06_generics.md
diff --git a/docs/docs/language_concepts/07_mutability.md → ...ocs/explanations/00_noir/07_mutability.md b/docs/docs/language_concepts/07_mutability.md → ...ocs/explanations/00_noir/07_mutability.md
diff --git a/docs/docs/language_concepts/08_lambdas.md → docs/docs/explanations/00_noir/08_lambdas.md b/docs/docs/language_concepts/08_lambdas.md → docs/docs/explanations/00_noir/08_lambdas.md
diff --git a/docs/docs/language_concepts/09_comments.md → .../docs/explanations/00_noir/09_comments.md b/docs/docs/language_concepts/09_comments.md → .../docs/explanations/00_noir/09_comments.md
diff --git a/docs/docs/language_concepts/10_distinct.md → .../docs/explanations/00_noir/10_distinct.md b/docs/docs/language_concepts/10_distinct.md → .../docs/explanations/00_noir/10_distinct.md
diff --git a/docs/docs/language_concepts/11_shadowing.md → ...docs/explanations/00_noir/11_shadowing.md b/docs/docs/language_concepts/11_shadowing.md → ...docs/explanations/00_noir/11_shadowing.md
diff --git a/docs/docs/language_concepts/12_data_bus.md → .../docs/explanations/00_noir/12_data_bus.md b/docs/docs/language_concepts/12_data_bus.md → .../docs/explanations/00_noir/12_data_bus.md
diff --git a/...ry/cryptographic_primitives/00_hashes.mdx → ...00_cryptographic_primitives/00_hashes.mdx b/...ry/cryptographic_primitives/00_hashes.mdx → ...00_cryptographic_primitives/00_hashes.mdx
diff --git a/...ry/cryptographic_primitives/01_scalar.mdx → ...00_cryptographic_primitives/01_scalar.mdx b/...ry/cryptographic_primitives/01_scalar.mdx → ...00_cryptographic_primitives/01_scalar.mdx
diff --git a/...y/cryptographic_primitives/02_schnorr.mdx → ...0_cryptographic_primitives/02_schnorr.mdx b/...y/cryptographic_primitives/02_schnorr.mdx → ...0_cryptographic_primitives/02_schnorr.mdx
diff --git a/..._primitives/03_ecdsa_sig_verification.mdx → ..._primitives/03_ecdsa_sig_verification.mdx b/..._primitives/03_ecdsa_sig_verification.mdx → ..._primitives/03_ecdsa_sig_verification.mdx
diff --git a/...ptographic_primitives/04_ec_primitives.md → ...ptographic_primitives/04_ec_primitives.md b/...ptographic_primitives/04_ec_primitives.md → ...ptographic_primitives/04_ec_primitives.md
diff --git a/...ary/cryptographic_primitives/05_eddsa.mdx → .../00_cryptographic_primitives/05_eddsa.mdx b/...ary/cryptographic_primitives/05_eddsa.mdx → .../00_cryptographic_primitives/05_eddsa.mdx
diff --git a/...ndard_library/cryptographic_primitives.md → ...rary/00_cryptographic_primitives/index.md b/...ndard_library/cryptographic_primitives.md → ...rary/00_cryptographic_primitives/index.md
@@ -1,5 +1,5 @@
 ---
-title: Cryptographic primitives in Noir
+title: Cryptographic Primitives
 description:
   Learn about the cryptographic primitives ready to use for any Noir project
 keywords:

diff --git a/docs/docs/standard_library/black_box_fns.md → ...ions/01_standard_library/black_box_fns.md b/docs/docs/standard_library/black_box_fns.md → ...ions/01_standard_library/black_box_fns.md
diff --git a/docs/docs/standard_library/logging.md → ...planations/01_standard_library/logging.md b/docs/docs/standard_library/logging.md → ...planations/01_standard_library/logging.md
diff --git a/docs/docs/standard_library/merkle_trees.md → ...tions/01_standard_library/merkle_trees.md b/docs/docs/standard_library/merkle_trees.md → ...tions/01_standard_library/merkle_trees.md
@@ -17,7 +17,7 @@ keywords:
 
 ## compute_merkle_root
 
-Returns the root of the tree from the provided leaf and its hash path, using a [Pedersen hash](cryptographic_primitives/00_hashes.mdx#pedersen_hash).
+Returns the root of the tree from the provided leaf and its hash path, using a [Pedersen hash](@site/docs/explanations/01_standard_library/00_cryptographic_primitives/00_hashes.mdx#pedersen_hash).
 
 ```rust
 fn compute_merkle_root(leaf : Field, index : Field, hash_path: [Field]) -> Field

diff --git a/docs/docs/standard_library/options.md → ...planations/01_standard_library/options.md b/docs/docs/standard_library/options.md → ...planations/01_standard_library/options.md
diff --git a/docs/docs/standard_library/recursion.md → ...anations/01_standard_library/recursion.md b/docs/docs/standard_library/recursion.md → ...anations/01_standard_library/recursion.md
diff --git a/docs/docs/standard_library/zeroed.md → ...xplanations/01_standard_library/zeroed.md b/docs/docs/standard_library/zeroed.md → ...xplanations/01_standard_library/zeroed.md
diff --git a/...es_packages_crates/crates_and_packages.md → ...es_packages_crates/crates_and_packages.md b/...es_packages_crates/crates_and_packages.md → ...es_packages_crates/crates_and_packages.md
diff --git a/...s/modules_packages_crates/dependencies.md → ...2_modules_packages_crates/dependencies.md b/...s/modules_packages_crates/dependencies.md → ...2_modules_packages_crates/dependencies.md
diff --git a/docs/docs/modules_packages_crates/modules.md → ...ons/02_modules_packages_crates/modules.md b/docs/docs/modules_packages_crates/modules.md → ...ons/02_modules_packages_crates/modules.md
diff --git a/...ocs/modules_packages_crates/workspaces.md → .../02_modules_packages_crates/workspaces.md b/...ocs/modules_packages_crates/workspaces.md → .../02_modules_packages_crates/workspaces.md
diff --git a/docs/docs/getting_started/00_installation/index.md b/docs/docs/getting_started/00_installation/index.md
@@ -0,0 +1,45 @@
+---
+title: Nargo Installation
+description:
+  nargo is a command line tool for interacting with Noir programs. This page is a quick guide on how to install Nargo though the most common and easy method, noirup
+keywords: [
+   Nargo
+   Noir
+   Rust
+   Cargo
+   Noirup
+   Installation
+   Terminal Commands
+   Version Check
+   Nightlies
+   Specific Versions
+   Branches
+   Noirup Repository
+]
+---
+
+`nargo` is the one-stop-shop for almost everything related with Noir. The name comes from our love for Rust and its package manager `cargo`.
+
+With `nargo`, you can start new projects, compile, execute, prove, verify, test, generate solidity contracts, and do pretty much all that is available in Noir.
+
+Similarly to `rustup`, we also maintain an easy installation method that covers most machines: `noirup`.
+
+## Installing Noirup
+
+Open a terminal on your machine, and write:
+
+```bash
+curl -L https://raw.githubusercontent.com/noir-lang/noirup/main/install | bash
+```
+
+Close the terminal, open another one, and run
+
+```bash
+noirup
+```
+
+Done. That's it. You should have the latest version working. You can check with `nargo --version`.
+
+You can also install nightlies, specific versions
+or branches, check out the [noirup repository](https://github.com/noir-lang/noirup) for more
+information.
diff --git a/.../getting_started/00_nargo_installation.md → .../00_installation/other_install_methods.md b/.../getting_started/00_nargo_installation.md → .../00_installation/other_install_methods.md
@@ -1,72 +1,37 @@
 ---
-title: Nargo Installation
+title: Alternative Install Methods
 description:
-  nargo is a command line tool for interacting with Noir programs (e.g. compiling, proving,
-  verifying and more). Learn how to install and use Nargo for your projects with this comprehensive
-  guide.
-keywords: [Nargo, command line tool, Noir programs, installation guide, how to use Nargo]
+  There are different ways to install Nargo, the one-stop shop and command-line tool for developing Noir programs. This guide explains other methods that don't rely on noirup, such as compiling from source, installing from binaries, and using WSL for windows
+keywords: [
+   Installation
+   Nargo
+   Noirup
+   Binaries
+   Compiling from Source
+   WSL for Windows
+   macOS
+   Linux
+   Nix
+   Direnv
+   Shell & editor experience
+   Building and testing
+   Uninstalling Nargo
+   Noir vs code extension
+]
 ---
 
-`nargo` is a command line tool for interacting with Noir programs (e.g. compiling, proving,
-verifying and more).
-
-Alternatively, the interactions can also be performed in [NoirJS](../noir_js/noir_js.md).
-
-### UltraPlonk
-
-Nargo versions <0.5.0 of `aztec_backend` and `aztec_wasm_backend` are based on the TurboPlonk
-version of Aztec Backend, which lacks efficient implementations of useful primitives (e.g. Keccak256 in 18k constraints, ECDSA verification in 36k constraints) that the UltraPlonk version offers.
 
 ## Installation
 
-There are four approaches for installing Nargo:
-
-- [Option 1: Noirup](#option-1-noirup)
-- [Option 2: Binaries](#option-2-binaries)
-- [Option 3: Compile from Source](#option-3-compile-from-source)
-- [Option 4: WSL for Windows](#option-4-wsl-for-windows)
-
-Optionally you can also install [Noir VS Code extension] for syntax highlighting.
-
-### Option 1: Noirup
-
-If you're on OSX or Linux, the easiest way to start using Noir and Nargo is via noirup. Just open a
-terminal and run:
-
-```bash
-curl -L https://raw.githubusercontent.com/noir-lang/noirup/main/install | bash
-```
-
-Close the terminal, open another one, and run
-
-```bash
-noirup
-```
+The most common method of installing Nargo is through [Noirup](@site/docs/getting_started/00_installation/index.md)
 
-Done, you should have the latest version working. You can check with `nargo --version`.
+However, there are other methods for installing Nargo:
 
-You can also install nightlies, specific versions
-or branches, check out the [noirup repository](https://github.com/noir-lang/noirup) for more
-information.
+- [Binaries](#binaries)
+- [Compiling from Source](#compile-from-source)
+- [WSL for Windows](#wsl-for-windows)
 
-#### GitHub Actions
-
-You can use `noirup` with GitHub Actions for CI/CD and automated testing. It is as simple as
-installing `noirup` and running tests in your GitHub Action `yml` file.
-
-See the
-[config file](https://github.com/TomAFrench/noir-hashes/blob/master/.github/workflows/noir.yml) in
-this repo containing hash functions in Noir for an example.
-
-#### Nightly versions
-
-To install the nightly version of Noir (updated daily) run:
-
-```bash
-noirup -n
-```
-
-### Option 2: Binaries
+### Binaries
 
 See [GitHub Releases](https://github.com/noir-lang/noir/releases) for the latest and previous
 platform specific binaries.
@@ -110,34 +75,11 @@ source ~/.bashrc
 
 #### Step 2
 
-Check if the installation was successful by running `nargo --help`.
+Check if the installation was successful by running `nargo --version`. You should get a version number.
 
 > **macOS:** If you are prompted with an OS alert, right-click and open the _nargo_ executable from
 > Finder. Close the new terminal popped up and `nargo` should now be accessible.
 
-For a successful installation, you should see something similar to the following after running the
-command:
-
-```sh
-$ nargo --help
-
-Noir's package manager
-
-Usage: nargo <COMMAND>
-
-Commands:
-   check             Checks the constraint system for errors
-   codegen-verifier  Generates a Solidity verifier smart contract for the program
-   compile           Compile the program and its secret execution trace into ACIR format
-   new               Create a new binary project
-   execute           Executes a circuit to calculate its return value
-   prove             Create proof for this program. The proof is returned as a hex encoded string
-   verify            Given a proof and a program, verify whether the proof is valid
-   test              Run the tests for this program
-   gates             Counts the occurrences of different gates in circuit
-   help              Print this message or the help of the given subcommand(s)
-```
-
 ### Option 3: Compile from Source
 
 Due to the large number of native dependencies, Noir projects uses [Nix](https://nixos.org/) and [direnv](https://direnv.net/) to streamline the development experience. It helps mitigating ssues commonly associated with dependency management, such as conflicts between required package versions for different projects (often referred to as "dependency hell").
@@ -224,7 +166,7 @@ The default backend for Noir (Barretenberg) doesn't provide Windows binaries at
 
 Step 1: Follow the instructions [here](https://learn.microsoft.com/en-us/windows/wsl/install) to install and run WSL.
 
-step 2: Follow the [Noirup instructions](#option-1-noirup).
+step 2: Follow the [Noirup instructions](@site/docs/getting_started/00_installation/index.md).
 
 ## Uninstalling Nargo
 
@@ -245,5 +187,3 @@ If you installed Noir with Nix or from source, you can remove the binary located
 ```bash
 rm ~/.nix-profile/bin/nargo
 ```
-
-[noir vs code extension]: https://marketplace.visualstudio.com/items?itemName=noir-lang.vscode-noir
diff --git a/docs/docs/getting_started/01_hello_world.md → ...cs/getting_started/01_create_a_project.md b/docs/docs/getting_started/01_hello_world.md → ...cs/getting_started/01_create_a_project.md
@@ -1,5 +1,5 @@
 ---
-title: Create A Project
+title: Creating A Project
 description:
   Learn how to create and verify your first Noir program using Nargo, a programming language for
   zero-knowledge proofs.
@@ -30,13 +30,6 @@ mkdir ~/projects
 cd ~/projects
 ```
 
-For Windows CMD, run:
-
-```sh
-> mkdir "%USERPROFILE%\projects"
-> cd /d "%USERPROFILE%\projects"
-```
-
 ## Create Our First Nargo Project
 
 Now that we are in the projects directory, create a new Nargo project by running:
@@ -74,7 +67,7 @@ x : Field, y : pub Field
 
 Program inputs in Noir are private by default (e.g. `x`), but can be labeled public using the
 keyword `pub` (e.g. `y`). To learn more about private and public values, check the
-[Data Types](../language_concepts/data_types) section.
+[Data Types](@site/docs/explanations/00_noir/00_data_types/index.md) section.
 
 The next line of the program specifies its body:
 
@@ -84,7 +77,7 @@ assert(x != y);
 
 The Noir syntax `assert` can be interpreted as something similar to constraints in other zk-contract languages.
 
-For more Noir syntax, check the [Language Concepts](../language_concepts/comments) chapter.
+For more Noir syntax, check the [Language Concepts](@site/docs/explanations/00_noir/09_comments.md) chapter.
 
 ## Build In/Output Files
 
@@ -144,4 +137,4 @@ corresponding error instead.
 
 Congratulations, you have now created and verified a proof for your very first Noir program!
 
-In the [next section](breakdown), we will go into more detail on each step performed.
+In the [next section](@site/docs/getting_started/02_project_breakdown.md), we will go into more detail on each step performed.
diff --git a/docs/docs/getting_started/02_breakdown.md → ...s/getting_started/02_project_breakdown.md b/docs/docs/getting_started/02_breakdown.md → ...s/getting_started/02_project_breakdown.md
@@ -51,7 +51,7 @@ license = "MIT"
 ecrecover = {tag = "v0.9.0", git = "https://github.com/colinnielsen/ecrecover-noir.git"}
 ```
 
-Nargo.toml for a [workspace](../modules_packages_crates/workspaces) will look a bit different. For example:
+Nargo.toml for a [workspace](@site/docs/explanations/02_modules_packages_crates/workspaces.md) will look a bit different. For example:
 
 ```toml
 [workspace]
@@ -74,7 +74,7 @@ The package section requires a number of fields including:
 
 #### Dependencies section
 
-This is where you will specify any dependencies for your project. See the [Dependencies page](../modules_packages_crates/dependencies) for more info.
+This is where you will specify any dependencies for your project. See the [Dependencies page](@site/docs/explanations/02_modules_packages_crates/dependencies.md) for more info.
 
 `./proofs/` and `./contract/` directories will not be immediately visible until you create a proof or
 verifier contract respectively.

diff --git a/docs/docs/nargo/04_language_server.md → ..._started/03_tooling/00_language_server.md b/docs/docs/nargo/04_language_server.md → ..._started/03_tooling/00_language_server.md
diff --git a/docs/docs/nargo/02_testing.md → .../getting_started/03_tooling/01_testing.md b/docs/docs/nargo/02_testing.md → .../getting_started/03_tooling/01_testing.md
diff --git a/docs/docs/getting_started/03_tooling/index.md b/docs/docs/getting_started/03_tooling/index.md
@@ -0,0 +1,33 @@
+---
+title: Tooling
+Description: This section provides information about the various tools and utilities available for Noir development. It covers the Noir playground, IDE tools, Codespaces, and community projects.
+Keywords: [Noir, Development, Playground, IDE Tools, Language Service Provider, VS Code Extension, Codespaces, noir-starter, Community Projects, Awesome Noir Repository, Developer Tooling]
+---
+
+Noir is meant to be easy to develop with. For that reason, a number of utilities have been put together to ease the development process as much as feasible in the zero-knowledge world.
+
+## Playground
+
+The Noir playground is an easy way to test small ideas, share snippets, and integrate in other websites. You can access it at [play.noir-lang.org](https://play.noir-lang.org).
+
+## IDE tools
+
+When you install Nargo, you're also installing a Language Service Provider (LSP), which can be used by IDEs to provide syntax highlighting, codelens, warnings, and more.
+
+The easiest way to use these tools is by installing the [Noir VS Code extension](https://marketplace.visualstudio.com/items?itemName=noir-lang.vscode-noir).
+
+## Codespaces
+
+Some Noir repos have leveraged Codespaces in order to ease the development process. You can visit the [noir-starter](https://github.com/noir-lang/noir-starter) for an example.
+
+## GitHub Actions
+
+You can use `noirup` with GitHub Actions for CI/CD and automated testing. It is as simple as
+installing `noirup` and running tests in your GitHub Action `yml` file.
+
+See the
+[config file in the Noir repo](https://github.com/TomAFrench/noir-hashes/blob/master/.github/workflows/noir.yml) for an example usage.
+
+## Community projects
+
+As an open-source project, Noir has received many contributions over time. Some of them are related with developer tooling, and you can see some of them in [Awesome Noir repository](https://github.com/noir-lang/awesome-noir#dev-tools)
diff --git a/docs/docs/nargo/03_solidity_verifier.md → docs/docs/how_to/03_solidity_verifier.md b/docs/docs/nargo/03_solidity_verifier.md → docs/docs/how_to/03_solidity_verifier.md
@@ -1,5 +1,5 @@
 ---
-title: Solidity Verifier
+title: Generate a Solidity Verifier
 description:
   Learn how to run the verifier as a smart contract on the blockchain. Compile a Solidity verifier
   contract for your Noir program and deploy it on any EVM blockchain acting as a verifier smart

diff --git a/docs/docs/examples/merkle-proof.mdx → docs/docs/how_to/merkle-proof.mdx b/docs/docs/examples/merkle-proof.mdx → docs/docs/how_to/merkle-proof.mdx
@@ -1,5 +1,5 @@
 ---
-title: Merkle Proof Membership
+title: Prove Merkle Tree Membership
 description:
   Learn how to use merkle membership proof in Noir to prove that a given leaf is a member of a
   merkle tree with a specified root, at a given index.