diff --git a/.github/workflows/deploy.yaml b/.github/workflows/deploy.yaml
index ca6ade9..889838c 100644
--- a/.github/workflows/deploy.yaml
+++ b/.github/workflows/deploy.yaml
@@ -20,7 +20,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
 
       - name: Install Nix
         uses: cachix/install-nix-action@v31
diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml
new file mode 100644
index 0000000..e9f0492
--- /dev/null
+++ b/.github/workflows/release.yaml
@@ -0,0 +1,32 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Install Nix
+        uses: cachix/install-nix-action@v31
+        with:
+          nix_path: nixpkgs=channel:nixos-25.11
+
+      - name: Build project
+        run: |
+          nix develop --command uv build
+
+      - name: Create Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: |
+            dist/stepcode-*
diff --git a/.gitignore b/.gitignore
index d12882f..3d1708c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -13,6 +13,7 @@ __pycache__/
 .pytest_cache/
 .ruff_cache/
 .mypy_cache/
+stepcode.egg-info/
 
 # ---
 dist/
diff --git a/docs/contribute/build.md b/docs/contribute/build.md
index 98aecf8..8085321 100644
--- a/docs/contribute/build.md
+++ b/docs/contribute/build.md
@@ -1,9 +1,28 @@
 ---
-title: 'How to build'
+title: 'How to build stepcode and the documentation'
 ---
 
 # {{title}}
 
 ## Building stepcode
 
+To build **stepcode** into source and binary distributions compatible with, for example, PyPI, you can use the following command:
+
+```sh
+uv build
+```
+
 ## Building our documentation
+
+To build the documentation, you can use:
+
+```sh
+uv run src/main.py docs
+```
+
+## Using nix
+If you are a [nix](https://nixos.org/) user, you can use the `devShell` provided by the `flake.nix` to easily set up a development environment with all the necessary dependencies. To enter the development shell, run: 
+
+```sh
+nix develop .
+```
diff --git a/docs/usage/book.md b/docs/usage/book.md
index af13fef..2ef1421 100644
--- a/docs/usage/book.md
+++ b/docs/usage/book.md
@@ -4,8 +4,77 @@ title: 'Create your own book'
 
 # {{title}}
 
-## How to create your own book
+Creating a static book with **stepcode** is as simple as writing standard Markdown.
 
-## How to deploy
+## Cloning the Repository
+
+As **stepcode** is made in Python, you must clone the repository and install the dependencies to use it. You can do this with the following commands:
+
+```sh
+git clone
+cd stepcode
+```
+
+To easily manage dependencies and virtual environments, we recommend using [uv](https://docs.astral.sh/uv/). To install the dependencies and run the project, use:
+
+```sh
+uv sync
+uv run src/main.py
+```
+
+## Creating Your Book
+
+To create your book, create a folder. There you must have a `stepcode.toml`:
+
+```toml
+[book]
+name = "My book"
+author = "Me of course"
+
+chapters = [
+    # here you must list all the chapters of your book, in order.
+    "blog/first-post.md",
+    "blog/second-post.md",
+
+    "cooking/first-recipe.md",
+]
+```
+
+and a index.md in the root of the folder:
+
+```markdown
+---
+title: 'My book'
+---
+
+# {{title}}
+
+Hi
+```
+
+### If you are a [nix](https://nixos.org/download/) user, the repo flake exposes a `devShell` to download all the dependencies and have a ready to use environment. You can enter it with:
+
+```sh
+nix develop .
+```
+
+Furthermore, a template book is available using:
+
+```sh
+nix flake new --template github:daniqss/stepcode#book my-book
+```
+
+## Building the Book
+
+Instructions on how to build and host your book can be found in the [README.md](https://github.com/daniqss/stepcode?tab=readme-ov-file#usage) of the repository.
+
+After using
+
+```sh
+uv run src/main.py <YOUR_FOLDER>
+```
 
 ### In Github Pages
+
+If you want to host your book on Github Pages, you can copy our [workflow](https://github.com/daniqss/stepcode/blob/main/.github/workflows/release.yaml)
+If you're using the template, it already contains a workflow that will automatically build and deploy your book to Github Pages on every push to the `main` branch. You can customize it as you wish, but make sure to update the path to the book in the workflow.
diff --git a/docs/usage/stepcode.md b/docs/usage/stepcode.md
index effd6fa..b0af02f 100644
--- a/docs/usage/stepcode.md
+++ b/docs/usage/stepcode.md
@@ -4,12 +4,6 @@ title: 'How to use stepcode'
 
 # {{title}}
 
-Creating a static book with **stepcode** is as simple as writing standard Markdown.
-
-## Creating Chapters
-
-To add a new chapter, simply create a `.md` file in the `content/chapters/` directory. The tool will automatically detect it and generate the corresponding HTML.
-
 ## Writing Pseudocode
 
 To enable step-by-step execution for your pseudocode, wrap your code blocks with the `stepcode` language identifier:
@@ -23,7 +17,3 @@ result := x + y
 ````
 
 The interpreter will parse these blocks and provide the interactive stepping functionality in the generated static site.
-
-## Building the Book
-
-Instructions on how to build and host your book can be found in the [README.md](https://github.com/daniqss/stepcode) of the repository.