From e2f332d57fc7fdeb02efded0e3c70320d12d128a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois=20Capon?=
 <46624375+FrancoisCapon@users.noreply.github.com>
Date: Mon, 1 Sep 2025 11:11:23 +0200
Subject: [PATCH 1/2] improve unix docker run

---
 docs/creating-your-site.md | 38 +++++++++++++++++++++++++++++++++++---
 1 file changed, 35 insertions(+), 3 deletions(-)

diff --git a/docs/creating-your-site.md b/docs/creating-your-site.md
index cd0378e778c..9d7f4f66abf 100644
--- a/docs/creating-your-site.md
+++ b/docs/creating-your-site.md
@@ -10,7 +10,18 @@ mkdocs new .
 
 Alternatively, if you're running Material for MkDocs from within Docker, use:
 
-=== "Unix, Powershell"
+
+=== "Unix"
+
+    ```
+    docker run --rm \
+               --user $(id -u):$(id -g) \
+               --volume $(pwd):/docs \
+               squidfunk/mkdocs-material \
+               new . # bootstrap project
+    ```
+
+=== "Powershell"
 
     ```
     docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material new .
@@ -210,7 +221,18 @@ mkdocs serve # (1)!
 
 If you're running Material for MkDocs from within Docker, use:
 
-=== "Unix, Powershell"
+=== "Unix"
+
+    ```
+    docker run --rm \
+               --user $(id -u):$(id -g) \
+               --volume $(pwd):/docs \
+               --publish 127.0.0.1:8000:8000 \
+               squidfunk/mkdocs-material
+               # serve by default (Ctrl + C to stop preview server)
+    ```
+
+=== "Powershell"
 
     ```
     docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
@@ -241,7 +263,17 @@ mkdocs build
 
 If you're running Material for MkDocs from within Docker, use:
 
-=== "Unix, Powershell"
+=== "Unix"
+
+    ```
+    docker run --rm \
+               --user $(id -u):$(id -g) \
+               --volume $(pwd):/docs \
+               squidfunk/mkdocs-material \
+               build # build static site in $(pwd)/site
+    ```
+
+=== "Powershell"
 
     ```
     docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material build

From 60675a1118f44d584ed21d734fea6d81cd9fe383 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois=20Capon?=
 <46624375+FrancoisCapon@users.noreply.github.com>
Date: Mon, 1 Sep 2025 11:18:53 +0200
Subject: [PATCH 2/2] explain steps in introduction

---
 docs/creating-your-site.md | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/docs/creating-your-site.md b/docs/creating-your-site.md
index 9d7f4f66abf..28f4d46183e 100644
--- a/docs/creating-your-site.md
+++ b/docs/creating-your-site.md
@@ -1,8 +1,10 @@
 # Creating your site
 
-After you've [installed] Material for MkDocs, you can bootstrap your project
-documentation using the `mkdocs` executable. Go to the directory where you want
-your project to be located and enter:
+After you've [installed] Material for MkDocs, you can bootstrap your documentation project then preview your documentation and finaly build your site using the `mkdocs` executable.
+
+## Bootstrap your project
+
+Go to the directory where you want your project to be located and enter:
 
 ```
 mkdocs new .