diff --git a/docs/nu-git-manager-sugar/extra/gm-report.md b/docs/nu-git-manager-sugar/extra/gm-report.md
index 9ebb0334..4a8a0955 100644
--- a/docs/nu-git-manager-sugar/extra/gm-report.md
+++ b/docs/nu-git-manager-sugar/extra/gm-report.md
@@ -1,8 +1,26 @@
-# `nu-git-manager-sugar extra gm report`
-## Description
+# `gm report` (`nu-git-manager-sugar extra`)
 get a full report about the local store of repositories
 
-
+## Examples
+```nushell
+gm report | columns
+```
+```
+╭────┬───────────╮
+│  0 │ name      │
+│  1 │ branch    │
+│  2 │ remote    │
+│  3 │ tag       │
+│  4 │ index     │
+│  5 │ ignored   │
+│  6 │ conflicts │
+│  7 │ ahead     │
+│  8 │ behind    │
+│  9 │ worktree  │
+│ 10 │ stashes   │
+│ 11 │ clean     │
+╰────┴───────────╯
+```
 
 ## Parameters
 
diff --git a/docs/nu-git-manager-sugar/git/gm-repo-branch-interactive-delete.md b/docs/nu-git-manager-sugar/git/gm-repo-branch-interactive-delete.md
index f4e0c8c5..e59cb88a 100644
--- a/docs/nu-git-manager-sugar/git/gm-repo-branch-interactive-delete.md
+++ b/docs/nu-git-manager-sugar/git/gm-repo-branch-interactive-delete.md
@@ -1,5 +1,4 @@
-# `nu-git-manager-sugar git gm repo branch interactive-delete`
-## Description
+# `gm repo branch interactive-delete` (`nu-git-manager-sugar git`)
 remove a branch interactively
 
 
@@ -8,6 +7,6 @@ remove a branch interactively
 
 
 ## Signatures
-| input | output |
-| ----- | ------ |
-| `any` | `any`  |
+| input     | output    |
+| --------- | --------- |
+| `nothing` | `nothing` |
diff --git a/docs/nu-git-manager-sugar/git/gm-repo-branch-wipe.md b/docs/nu-git-manager-sugar/git/gm-repo-branch-wipe.md
index 1234e38f..965c179b 100644
--- a/docs/nu-git-manager-sugar/git/gm-repo-branch-wipe.md
+++ b/docs/nu-git-manager-sugar/git/gm-repo-branch-wipe.md
@@ -1,5 +1,4 @@
-# `nu-git-manager-sugar git gm repo branch wipe`
-## Description
+# `gm repo branch wipe` (`nu-git-manager-sugar git`)
 wipe a branch completely, i.e. both locally and remotely
 
 
@@ -18,6 +17,6 @@ wipe a branch completely, i.e. both locally and remotely
 - description: the remote to push to
 
 ## Signatures
-| input | output |
-| ----- | ------ |
-| `any` | `any`  |
+| input     | output    |
+| --------- | --------- |
+| `nothing` | `nothing` |
diff --git a/docs/nu-git-manager-sugar/git/gm-repo-branches.md b/docs/nu-git-manager-sugar/git/gm-repo-branches.md
index 8f45d669..5c4f0562 100644
--- a/docs/nu-git-manager-sugar/git/gm-repo-branches.md
+++ b/docs/nu-git-manager-sugar/git/gm-repo-branches.md
@@ -1,17 +1,20 @@
-# `nu-git-manager-sugar git gm repo branches`
-## Description
+# `gm repo branches` (`nu-git-manager-sugar git`)
 inspect local branches
 
 > **Note**  
 > in the following, a "*dangling*" branch refers to a branch that does not have any remote
 > counterpart, i.e. it's a purely local branch.
 
-# Examples
-    list branches and their associated remotes
-    > gm repo branches
-
-    clean all dangling branches
-    > gm repo branches --clean
+## Examples
+```nushell
+# list branches and their associated remotes
+gm repo branches
+```
+---
+```nushell
+# clean all dangling branches
+gm repo branches --clean
+```
 
 ## Parameters
 - parameter_name: clean
diff --git a/docs/nu-git-manager-sugar/git/gm-repo-compare.md b/docs/nu-git-manager-sugar/git/gm-repo-compare.md
index 4579981e..212e41a4 100644
--- a/docs/nu-git-manager-sugar/git/gm-repo-compare.md
+++ b/docs/nu-git-manager-sugar/git/gm-repo-compare.md
@@ -1,5 +1,4 @@
-# `nu-git-manager-sugar git gm repo compare`
-## Description
+# `gm repo compare` (`nu-git-manager-sugar git`)
 compare the changes between two revisions, from a target to the "head"
 
 
@@ -19,6 +18,6 @@ compare the changes between two revisions, from a target to the "head"
 - parameter_default: HEAD
 
 ## Signatures
-| input | output |
-| ----- | ------ |
-| `any` | `any`  |
+| input     | output   |
+| --------- | -------- |
+| `nothing` | `string` |
diff --git a/docs/nu-git-manager-sugar/git/gm-repo-fetch-branch.md b/docs/nu-git-manager-sugar/git/gm-repo-fetch-branch.md
index f201e006..535856c3 100644
--- a/docs/nu-git-manager-sugar/git/gm-repo-fetch-branch.md
+++ b/docs/nu-git-manager-sugar/git/gm-repo-fetch-branch.md
@@ -1,5 +1,4 @@
-# `nu-git-manager-sugar git gm repo fetch branch`
-## Description
+# `gm repo fetch branch` (`nu-git-manager-sugar git`)
 fetch a remote branch locally, without pulling down the whole remote
 
 
@@ -25,6 +24,6 @@ fetch a remote branch locally, without pulling down the whole remote
 - parameter_default: none
 
 ## Signatures
-| input | output |
-| ----- | ------ |
-| `any` | `any`  |
+| input     | output    |
+| --------- | --------- |
+| `nothing` | `nothing` |
diff --git a/docs/nu-git-manager-sugar/git/gm-repo-get-commit.md b/docs/nu-git-manager-sugar/git/gm-repo-get-commit.md
index 69cb0426..fa735f7b 100644
--- a/docs/nu-git-manager-sugar/git/gm-repo-get-commit.md
+++ b/docs/nu-git-manager-sugar/git/gm-repo-get-commit.md
@@ -1,13 +1,16 @@
-# `nu-git-manager-sugar git gm repo get commit`
-## Description
+# `gm repo get commit` (`nu-git-manager-sugar git`)
 get the commit hash of any revision
 
-# Examples
-    get the commit hash of the currently checked out revision
-    > gm repo get commit
-
-    get the commit hash of the main branch
-    > gm repo get commit main
+## Examples
+```nushell
+# get the commit hash of the currently checked out revision
+gm repo get commit
+```
+---
+```nushell
+# get the commit hash of the main branch
+gm repo get commit main
+```
 
 ## Parameters
 - parameter_name: revision
diff --git a/docs/nu-git-manager-sugar/git/gm-repo-goto-root.md b/docs/nu-git-manager-sugar/git/gm-repo-goto-root.md
index 6b58323e..751495c9 100644
--- a/docs/nu-git-manager-sugar/git/gm-repo-goto-root.md
+++ b/docs/nu-git-manager-sugar/git/gm-repo-goto-root.md
@@ -1,11 +1,14 @@
-# `nu-git-manager-sugar git gm repo goto root`
-## Description
+# `gm repo goto root` (`nu-git-manager-sugar git`)
 go to the root of the repository from anywhere in the worktree
 
-# Examples
-    go back to the root of a repo
-    > cd foo/bar/baz; gm repo goto root; print (pwd)
-    /path/to/repo
+## Examples
+```nushell
+# go back to the root of a repo
+cd foo/bar/baz; gm repo goto root; print (pwd)
+```
+```
+/path/to/repo
+```
 
 ## Parameters
 
diff --git a/docs/nu-git-manager-sugar/git/gm-repo-is-ancestor.md b/docs/nu-git-manager-sugar/git/gm-repo-is-ancestor.md
index 81c62a1b..bbcc93be 100644
--- a/docs/nu-git-manager-sugar/git/gm-repo-is-ancestor.md
+++ b/docs/nu-git-manager-sugar/git/gm-repo-is-ancestor.md
@@ -1,15 +1,22 @@
-# `nu-git-manager-sugar git gm repo is-ancestor`
-## Description
+# `gm repo is-ancestor` (`nu-git-manager-sugar git`)
 return true iif the first revision is an ancestor of the second
 
-# Examples
-    HEAD~20 is an ancestor of HEAD
-    > gm repo is-ancestor HEAD~20 HEAD
-    true
-
-    HEAD is never an ancestor of HEAD~20
-    > gm repo is-ancestor HEAD HEAD~20
-    false
+## Examples
+```nushell
+# HEAD~20 is an ancestor of HEAD
+gm repo is-ancestor HEAD~20 HEAD
+```
+```
+true
+```
+---
+```nushell
+# HEAD is never an ancestor of HEAD~20
+gm repo is-ancestor HEAD HEAD~20
+```
+```
+false
+```
 
 ## Parameters
 - parameter_name: a
diff --git a/docs/nu-git-manager-sugar/git/gm-repo-ls.md b/docs/nu-git-manager-sugar/git/gm-repo-ls.md
index 90cf2397..7ea01e4b 100644
--- a/docs/nu-git-manager-sugar/git/gm-repo-ls.md
+++ b/docs/nu-git-manager-sugar/git/gm-repo-ls.md
@@ -1,5 +1,4 @@
-# `nu-git-manager-sugar git gm repo ls`
-## Description
+# `gm repo ls` (`nu-git-manager-sugar git`)
 get some information about a repo
 
 
diff --git a/docs/nu-git-manager-sugar/git/gm-repo-query.md b/docs/nu-git-manager-sugar/git/gm-repo-query.md
index 83404af3..03fcd2a6 100644
--- a/docs/nu-git-manager-sugar/git/gm-repo-query.md
+++ b/docs/nu-git-manager-sugar/git/gm-repo-query.md
@@ -1,8 +1,28 @@
-# `nu-git-manager-sugar git gm repo query`
-## Description
-TODO: documentation
-
+# `gm repo query` (`nu-git-manager-sugar git`)
+queries the `.git/` directory as a database with `nu_plugin_git_query`
 
+## Examples
+```nushell
+# get the commits of the current repo
+gm repo query commits
+```
+---
+```nushell
+# get the total number of insertions and deletions per author
+gm repo query diffs
+    | group-by name
+    | transpose author data
+    | insert insertions { get data.insertions | math sum }
+    | insert deletions { get data.deletions | math sum }
+    | reject data
+```
+```
+#┬────author────┬insertions┬deletions
+0│amtoine       │      6770│     5402
+1│Antoine Stevan│      8537│     4562
+2│Mel Massadian │       654│       64
+─┴──────────────┴──────────┴─────────
+```
 
 ## Parameters
 - parameter_name: table
diff --git a/docs/nu-git-manager-sugar/git/gm-repo-remote-list.md b/docs/nu-git-manager-sugar/git/gm-repo-remote-list.md
index 392d15da..d7045395 100644
--- a/docs/nu-git-manager-sugar/git/gm-repo-remote-list.md
+++ b/docs/nu-git-manager-sugar/git/gm-repo-remote-list.md
@@ -1,14 +1,16 @@
-# `nu-git-manager-sugar git gm repo remote list`
-## Description
+# `gm repo remote list` (`nu-git-manager-sugar git`)
 get the list of all the remotes in the current repository
-# Examples
-    list all the remotes in a default `nu-git-manager` repo
-    > gm repo remote list
-    #┬remote┬──────────────────fetch──────────────────┬─────────────────push──────────────────
-    0│origin│https://github.com/amtoine/nu-git-manager│ssh://github.com/amtoine/nu-git-manager
-    ─┴──────┴─────────────────────────────────────────┴───────────────────────────────────────
-
 
+## Examples
+```nushell
+# list all the remotes in a default `nu-git-manager` repo
+gm repo remote list
+```
+```
+#┬remote┬──────────────────fetch──────────────────┬─────────────────push──────────────────
+0│origin│https://github.com/amtoine/nu-git-manager│ssh://github.com/amtoine/nu-git-manager
+─┴──────┴─────────────────────────────────────────┴───────────────────────────────────────
+```
 
 ## Parameters
 
diff --git a/docs/nu-git-manager-sugar/git/gm-repo-switch.md b/docs/nu-git-manager-sugar/git/gm-repo-switch.md
index 1c05af50..e2826945 100644
--- a/docs/nu-git-manager-sugar/git/gm-repo-switch.md
+++ b/docs/nu-git-manager-sugar/git/gm-repo-switch.md
@@ -1,5 +1,4 @@
-# `nu-git-manager-sugar git gm repo switch`
-## Description
+# `gm repo switch` (`nu-git-manager-sugar git`)
 switch between branches interactively
 
 
diff --git a/docs/nu-git-manager-sugar/git/prompt/setup.md b/docs/nu-git-manager-sugar/git/prompt/setup.md
index 29035074..0815a6b7 100644
--- a/docs/nu-git-manager-sugar/git/prompt/setup.md
+++ b/docs/nu-git-manager-sugar/git/prompt/setup.md
@@ -1,31 +1,58 @@
-# `nu-git-manager-sugar git prompt setup`
-## Description
+# `setup` (`nu-git-manager-sugar git prompt`)
 setup the Git prompt of NGM
 
 the different sections of the prompt are the following, in order and separated by a single space:
-- "admin_segment": shows if you are an admin of the session
-- "pwd": shows the current working directory, in long form outside of a repo or with only the
+- "_admin_": shows if you are an admin of the session
+- "_pwd_": shows the current working directory, in long form outside of a repo or with only the
     basename if inside a Git repo
-- "git_branch_segment": if inside a Git repo, will show the current branch, the tag or the
+- "_Git branch_": if inside a Git repo, will show the current branch, the tag or the
     detached revision
-- "git_action_segment": if inside a Git repo and performing a Git action, such as a MERGE or a
+- "_Git action_": if inside a Git repo and performing a Git action, such as a MERGE or a
     REBASE, the prompt will show the stage of the action
-- "duration_segment": if the last command took longer than the `--duration-threshold`, the prompt
+- "_duration_": if the last command took longer than the `--duration-threshold`, the prompt
     will show the exact duration
-- "command_failed_segment": if the last command failed, the exit code will be shown
-- "login_segment": shows if you are in a login session
+- "_command failed_": if the last command failed, the exit code will be shown
+- "_login_": shows if you are in a login session
 
-# Examples
-    setup the prompt with 10sec of command duration and `> ` as the Vi indicator
-    > export-env {
-          use nu-git-manager-sugar git-prompt setup
-          setup --duration-threshold 10sec --indicators {
-              vi: {
-                  insert: "> "
-                  normal: "> "
-              }
-          }
-      }
+## the look
+- outside of a Git repo
+```
+~/documents/repos/github.com >
+```
+- on a branch
+```
+nu-git-manager (main:c2242b4) >
+```
+- with the `HEAD` detached
+```
+nu-git-manager (_:adca8cb) >
+```
+- on a tag
+```
+nu-git-manager (0.3.0:3fb5c89) >
+```
+- during a rebase
+```
+nu-git-manager (_:5d8245d) (REBASE-i) >
+```
+- inside a subdirectory
+```
+nu-git-manager/src/nu-git-manager (main:c2242b4) >
+```
+
+## Examples
+```nushell
+# setup the prompt with 10sec of command duration and `> ` as the Vi indicator
+export-env {
+    use nu-git-manager-sugar git-prompt setup
+    setup --duration-threshold 10sec --indicators {
+        vi: {
+            insert: "> "
+            normal: "> "
+        }
+    }
+}
+```
 
 ## Parameters
 - parameter_name: indicators
@@ -42,6 +69,6 @@ the different sections of the prompt are the following, in order and separated b
 - parameter_default: 1sec
 
 ## Signatures
-| input | output |
-| ----- | ------ |
-| `any` | `any`  |
+| input     | output    |
+| --------- | --------- |
+| `nothing` | `nothing` |
diff --git a/docs/nu-git-manager-sugar/github/gm-gh-pr-checkout.md b/docs/nu-git-manager-sugar/github/gm-gh-pr-checkout.md
index c8fc778b..635b72ef 100644
--- a/docs/nu-git-manager-sugar/github/gm-gh-pr-checkout.md
+++ b/docs/nu-git-manager-sugar/github/gm-gh-pr-checkout.md
@@ -1,5 +1,4 @@
-# `nu-git-manager-sugar github gm gh pr checkout`
-## Description
+# `gm gh pr checkout` (`nu-git-manager-sugar github`)
 checkout one of the repo's PR interactively
 
 
@@ -8,6 +7,6 @@ checkout one of the repo's PR interactively
 
 
 ## Signatures
-| input | output |
-| ----- | ------ |
-| `any` | `any`  |
+| input     | output    |
+| --------- | --------- |
+| `nothing` | `nothing` |
diff --git a/docs/nu-git-manager-sugar/github/gm-gh-query-api.md b/docs/nu-git-manager-sugar/github/gm-gh-query-api.md
index 0c7c1b80..20209a1b 100644
--- a/docs/nu-git-manager-sugar/github/gm-gh-query-api.md
+++ b/docs/nu-git-manager-sugar/github/gm-gh-query-api.md
@@ -1,22 +1,27 @@
-# `nu-git-manager-sugar github gm gh query-api`
-## Description
+# `gm gh query-api` (`nu-git-manager-sugar github`)
 query the GitHub API for any end point
 
 > :bulb: **Note**  
 > see the [rest API of GitHub](https://docs.github.com/en/rest) for a complete
 > list of available end points and documentation
 
-# Examples
-    list the releases of Nushell sorted by date
-    > gm gh query-api "/repos/nushell/nushell/releases"
-          | select tag_name published_at
-          | rename tag date
-          | into datetime date
-          | sort-by date
-
-    get the bio of @amtoine
-    > gm gh query-api --no-paginate "/users/amtoine" | get bio
-    you shall not rebase in the middle of a PR review nor close other's review threads :pray:
+## Examples
+```nushell
+# list the releases of Nushell sorted by date
+gm gh query-api "/repos/nushell/nushell/releases"
+    | select tag_name published_at
+    | rename tag date
+    | into datetime date
+    | sort-by date
+```
+---
+```nushell
+# get the bio of @amtoine
+gm gh query-api --no-paginate "/users/amtoine" | get bio
+```
+```
+you shall not rebase in the middle of a PR review nor close other's review threads :pray:
+```
 
 ## Parameters
 - parameter_name: end_point
diff --git a/docs/nu-git-manager-sugar/github/gm-gh-query-releases.md b/docs/nu-git-manager-sugar/github/gm-gh-query-releases.md
index 8f4d0b41..fc427a86 100644
--- a/docs/nu-git-manager-sugar/github/gm-gh-query-releases.md
+++ b/docs/nu-git-manager-sugar/github/gm-gh-query-releases.md
@@ -1,14 +1,15 @@
-# `nu-git-manager-sugar github gm gh query-releases`
-## Description
+# `gm gh query-releases` (`nu-git-manager-sugar github`)
 list the releases of a GitHub repository
 
-# Examples
-    get the last release of the `github.com:nushell/nushell` repository
-    > gm gh query-releases "nushell/nushell"
-          | into datetime published_at
-          | sort-by published_at
-          | last
-          | select tag_name published_at
+## Examples
+```nushell
+# get the last release of the `github.com:nushell/nushell` repository
+gm gh query-releases "nushell/nushell"
+    | into datetime published_at
+    | sort-by published_at
+    | last
+    | select tag_name published_at
+```
 
 ## Parameters
 - parameter_name: repo
diff --git a/docs/nu-git-manager-sugar/github/gm-gh-query-user.md b/docs/nu-git-manager-sugar/github/gm-gh-query-user.md
index b587c74c..9b8ba738 100644
--- a/docs/nu-git-manager-sugar/github/gm-gh-query-user.md
+++ b/docs/nu-git-manager-sugar/github/gm-gh-query-user.md
@@ -1,10 +1,11 @@
-# `nu-git-manager-sugar github gm gh query-user`
-## Description
+# `gm gh query-user` (`nu-git-manager-sugar github`)
 get information about a GitHub user
 
-Examples:
-    get the avatar picture of @amtoine
-    > gm gh query-user amtoine | get avatar_url | http get $in | save --force amtoine.png
+## Examples:
+```nushell
+# get the avatar picture of @amtoine
+gm gh query-user amtoine | get avatar_url | http get $in | save --force amtoine.png
+```
 
 ## Parameters
 - parameter_name: user
diff --git a/docs/nu-git-manager/gm-clean.md b/docs/nu-git-manager/gm-clean.md
index 3154398f..ca952d45 100644
--- a/docs/nu-git-manager/gm-clean.md
+++ b/docs/nu-git-manager/gm-clean.md
@@ -1,17 +1,20 @@
-# `nu-git-manager gm clean`
-## Description
+# `gm clean` (`nu-git-manager`)
 clean the store
 
 this command will mainly remove empty directory recursively.
 
-/!\ this command will return sanitized paths. /!\
+**/!\\** this command will return sanitized paths. **/!\\**
 
-Examples
-    clean the store
-    > gm clean
-
-    list the leaves of the store that would have to be cleaned
-    > gm clean --list
+## Examples
+```nushell
+# clean the store
+gm clean
+```
+---
+```nushell
+# list the leaves of the store that would have to be cleaned
+gm clean --list
+```
 
 ## Parameters
 - parameter_name: list
diff --git a/docs/nu-git-manager/gm-clone.md b/docs/nu-git-manager/gm-clone.md
index 8703e552..b9605ffa 100644
--- a/docs/nu-git-manager/gm-clone.md
+++ b/docs/nu-git-manager/gm-clone.md
@@ -1,24 +1,33 @@
-# `nu-git-manager gm clone`
-## Description
+# `gm clone` (`nu-git-manager`)
 clone a remote Git repository into your local store
 
 will give a nice error if the repository is already in the local store.
 
-# Examples
-    clone a repository in the local store of `nu-git-manager`
-    > gm clone https://github.com/amtoine/nu-git-manager
-
-    clone as a bare repository, i.e. a repo without a worktree
-    > gm clone --bare https://github.com/amtoine/nu-git-manager
-
-    clone a repo and change the name of the remote
-    > gm clone --remote default https://github.com/amtoine/nu-git-manager
-
-    setup a public repo in the local store and use HTTP to fetch without PAT and push with SSH
-    > gm clone https://github.com/amtoine/nu-git-manager --fetch https --push ssh
-
-    clone a big repo as a single commit, avoiding all intermediate Git deltas
-    > gm clone https://github.com/neovim/neovim --depth 1
+## Examples
+```nushell
+# clone a repository in the local store of `nu-git-manager`
+gm clone https://github.com/amtoine/nu-git-manager
+```
+---
+```nushell
+# clone as a bare repository, i.e. a repo without a worktree
+gm clone --bare https://github.com/amtoine/nu-git-manager
+```
+---
+```nushell
+# clone a repo and change the name of the remote
+gm clone --remote default https://github.com/amtoine/nu-git-manager
+```
+---
+```nushell
+# setup a public repo in the local store and use HTTP to fetch without PAT and push with SSH
+gm clone https://github.com/amtoine/nu-git-manager --fetch https --push ssh
+```
+---
+```nushell
+# clone a big repo as a single commit, avoiding all intermediate Git deltas
+gm clone https://github.com/neovim/neovim --depth 1
+```
 
 ## Parameters
 - parameter_name: url
diff --git a/docs/nu-git-manager/gm-list.md b/docs/nu-git-manager/gm-list.md
index 532fb08a..7bb0e771 100644
--- a/docs/nu-git-manager/gm-list.md
+++ b/docs/nu-git-manager/gm-list.md
@@ -1,18 +1,23 @@
-# `nu-git-manager gm list`
-## Description
+# `gm list` (`nu-git-manager`)
 list all the local repositories in your local store
 
-/!\ this command will return sanitized paths. /!\
+**/!\\** this command will return sanitized paths. **/!\\**
 
-# Examples
-    list all the repositories in the store
-    > gm list
-
-    list all the repositories in the store with their full paths
-    > gm list --full-path
-
-    jump to a directory in the store
-    > cd (gm list --full-path | input list)
+## Examples
+```nushell
+# list all the repositories in the store
+gm list
+```
+---
+```nushell
+# list all the repositories in the store with their full paths
+gm list --full-path
+```
+---
+```nushell
+# jump to a directory in the store
+cd (gm list --full-path | input list)
+```
 
 ## Parameters
 - parameter_name: full-path
diff --git a/docs/nu-git-manager/gm-remove.md b/docs/nu-git-manager/gm-remove.md
index 4735b817..832972b4 100644
--- a/docs/nu-git-manager/gm-remove.md
+++ b/docs/nu-git-manager/gm-remove.md
@@ -1,19 +1,26 @@
-# `nu-git-manager gm remove`
-## Description
+# `gm remove` (`nu-git-manager`)
 remove one of the repositories from your local store
 
-# Examples
-    remove any repository by fuzzy-finding the whole store
-    > gm remove --fuzzy
-
-    restrict the search to any one of my repositories
-    > gm remove amtoine
-
-    remove a precise repo by giving its full name, a name collision is unlikely
-    > gm remove amtoine/nu-git-manager
-
-    remove a precise repo without confirmation
-    > gm remove amtoine/nu-git-manager --no-confirm
+## Examples
+```nushell
+# remove any repository by fuzzy-finding the whole store
+gm remove --fuzzy
+```
+---
+```nushell
+# restrict the search to any one of my repositories
+gm remove amtoine
+```
+---
+```nushell
+# remove a precise repo by giving its full name, a name collision is unlikely
+gm remove amtoine/nu-git-manager
+```
+---
+```nushell
+# remove a precise repo without confirmation
+gm remove amtoine/nu-git-manager --no-confirm
+```
 
 ## Parameters
 - parameter_name: pattern
diff --git a/docs/nu-git-manager/gm-squash-forks.md b/docs/nu-git-manager/gm-squash-forks.md
index 66a5cedd..91973ab0 100644
--- a/docs/nu-git-manager/gm-squash-forks.md
+++ b/docs/nu-git-manager/gm-squash-forks.md
@@ -1,5 +1,4 @@
-# `nu-git-manager gm squash-forks`
-## Description
+# `gm squash-forks` (`nu-git-manager`)
 squash multi-directory forks into a single repo
 
 Here, two forks are defined as *two non-grafted repositories that share the same initial commit,
@@ -18,15 +17,19 @@ This option is a `record` with
 - keys: the root hash of repos, e.g. [2ed2d87](https://github.com/amtoine/nu-git-manager/commit/2ed2d875d80505d78423328c6b2a60522715fcdf) for `nu-git-manager`
 - values: the main fork to select in full-name form, e.g. `github.com/amtoine/nu-git-manager`
 
-# Examples
-    squash forks interactively
-    > gm squash-forks
-
-    squash forks non-interactively: `nu-git-manager` and `nushell` to the forks of @amtoine
-    > gm squash-forks --non-interactive-preselect {
-          2ed2d875d80505d78423328c6b2a60522715fcdf: "github.com/amtoine/nu-git-manager",
-          8f3b273337b53bd86d5594d5edc9d4ad7242bd4c: "github.com/amtoine/nushell",
-      }
+## Examples
+```nushell
+# squash forks interactively
+gm squash-forks
+```
+---
+```nushell
+# squash forks non-interactively: `nu-git-manager` and `nushell` to the forks of @amtoine
+gm squash-forks --non-interactive-preselect {
+    2ed2d875d80505d78423328c6b2a60522715fcdf: "github.com/amtoine/nu-git-manager",
+    8f3b273337b53bd86d5594d5edc9d4ad7242bd4c: "github.com/amtoine/nushell",
+}
+```
 
 ## Parameters
 - parameter_name: non-interactive-preselect
diff --git a/docs/nu-git-manager/gm-status.md b/docs/nu-git-manager/gm-status.md
index 38d34f07..2cb02f8d 100644
--- a/docs/nu-git-manager/gm-status.md
+++ b/docs/nu-git-manager/gm-status.md
@@ -1,42 +1,59 @@
-# `nu-git-manager gm status`
-## Description
-get current status about the repositories managed by `nu-git-manager`
+# `gm status` (`nu-git-manager`)
+get current status about the repositories managed by NGM
 
-/!\ `$.root.path` and `$.cache.path` will be sanitized /!\
+**/!\\** `$.root.path` and `$.cache.path` will be sanitized **/!\\**
 
-Examples
-    getting status when everything is fine
-    > gm status | reject missing | flatten | into record
-    ╭─────────────────────┬────────────────────────────────────╮
-    │ path                │ ~/.local/share/repos               │
-    │ exists              │ true                               │
-    │ cache_path          │ ~/.cache/nu-git-manager/cache.nuon │
-    │ cache_exists        │ true                               │
-    │ should_update_cache │ false                              │
-    ╰─────────────────────┴────────────────────────────────────╯
-
-    getting status when there is no store
-    > gm status | get root
-    ╭────────┬──────────────────────╮
-    │ path   │ ~/.local/share/repos │
-    │ exists │ false                │
-    ╰────────┴──────────────────────╯
-
-    getting status when there is no cache
-    > gm status | get root
-    ╭────────┬────────────────────────────────────╮
-    │ path   │ ~/.cache/nu-git-manager/cache.nuon │
-    │ exists │ false                              │
-    ╰────────┴────────────────────────────────────╯
-
-    getting status when a project is in the cache but is missing on the filesystem
-    > gm status | get missing
-    ╭──────────────────────────────────────╮
-    │ 0 │ ~/.local/share/repos/foo/bar/baz │
-    ╰──────────────────────────────────────╯
-
-    update the cache if necessary
-    > if (gm status).should_update_cache { gm update-cache }
+## Examples
+```nushell
+# getting status when everything is fine
+gm status | reject missing | flatten | into record
+```
+```
+╭─────────────────────┬────────────────────────────────────╮
+│ path                │ ~/.local/share/repos               │
+│ exists              │ true                               │
+│ cache_path          │ ~/.cache/nu-git-manager/cache.nuon │
+│ cache_exists        │ true                               │
+│ should_update_cache │ false                              │
+╰─────────────────────┴────────────────────────────────────╯
+```
+---
+```nushell
+# getting status when there is no store
+gm status | get root
+```
+```
+╭────────┬──────────────────────╮
+│ path   │ ~/.local/share/repos │
+│ exists │ false                │
+╰────────┴──────────────────────╯
+```
+---
+```nushell
+# getting status when there is no cache
+gm status | get root
+```
+```
+╭────────┬────────────────────────────────────╮
+│ path   │ ~/.cache/nu-git-manager/cache.nuon │
+│ exists │ false                              │
+╰────────┴────────────────────────────────────╯
+```
+---
+```nushell
+# getting status when a project is in the cache but is missing on the filesystem
+gm status | get missing
+```
+```
+╭──────────────────────────────────────╮
+│ 0 │ ~/.local/share/repos/foo/bar/baz │
+╰──────────────────────────────────────╯
+```
+---
+```nushell
+# update the cache if necessary
+if (gm status).should_update_cache { gm update-cache }
+```
 
 ## Parameters
 
diff --git a/docs/nu-git-manager/gm-update-cache.md b/docs/nu-git-manager/gm-update-cache.md
index f93ae396..83f6b33b 100644
--- a/docs/nu-git-manager/gm-update-cache.md
+++ b/docs/nu-git-manager/gm-update-cache.md
@@ -1,10 +1,11 @@
-# `nu-git-manager gm update-cache`
-## Description
+# `gm update-cache` (`nu-git-manager`)
 update the local cache of repositories
 
-# Examples
-    update the cache of repositories
-    > gm update-cache
+## Examples
+```nushell
+# update the cache of repositories
+gm update-cache
+```
 
 ## Parameters
 
diff --git a/docs/nu-git-manager/gm.md b/docs/nu-git-manager/gm.md
index 462429e3..51883135 100644
--- a/docs/nu-git-manager/gm.md
+++ b/docs/nu-git-manager/gm.md
@@ -1,29 +1,38 @@
-# `nu-git-manager gm`
-## Description
-manage your Git repositories with the main command of `nu-git-manager`
+# `gm` (`nu-git-manager`)
+manage your Git repositories with the main command of NGM
 
-`nu-git-manager` will look for a store in the following places, in order:
+### the location for the store
+NGM will look for a store in the following places, in order:
 - `$env.GIT_REPOS_HOME`
-- `$env.XDG_DATA_HOME | path join "repos"
+- `$env.XDG_DATA_HOME | path join "repos"`
 - `~/.local/share/repos`
 
-`nu-git-manager` will look for a cache in the following places, in order:
+### the cache
+NGM will look for a cache in the following places, in order:
 - `$env.GIT_REPOS_CACHE`
-- `$env.XDG_CACHE_HOME | path join "nu-git-manager/cache.nuon"
+- `$env.XDG_CACHE_HOME | path join "nu-git-manager/cache.nuon"`
 - `~/.cache/nu-git-manager/cache.nuon`
 
-# Examples
-    a contrived example to set the path to the root of the store
-    > with-env { GIT_REPOS_HOME: ($nu.home-path | path join "foo") } {
-          gm status | get root.path | str replace $nu.home-path '~'
-      }
-    ~/foo
-
-    a contrived example to set the path to the cache of the store
-    > with-env { XDG_CACHE_HOME: ($nu.home-path | path join "foo") } {
-          gm status | get cache.path | str replace $nu.home-path '~'
-      }
-    ~/foo/nu-git-manager/cache.nuon
+## Examples
+```nushell
+# a contrived example to set the path to the root of the store
+with-env { GIT_REPOS_HOME: ($nu.home-path | path join "foo") } {
+    gm status | get root.path | str replace $nu.home-path '~'
+}
+```
+```
+~/foo
+```
+---
+```nushell
+# a contrived example to set the path to the cache of the store
+with-env { XDG_CACHE_HOME: ($nu.home-path | path join "foo") } {
+    gm status | get cache.path | str replace $nu.home-path '~'
+}
+```
+```
+~/foo/nu-git-manager/cache.nuon
+```
 
 ## Parameters
 
diff --git a/src/nu-git-manager-sugar/extra.nu b/src/nu-git-manager-sugar/extra.nu
index eb4e9290..79b2e4b5 100644
--- a/src/nu-git-manager-sugar/extra.nu
+++ b/src/nu-git-manager-sugar/extra.nu
@@ -1,4 +1,25 @@
 # get a full report about the local store of repositories
+#
+# ## Examples
+# ```nushell
+# gm report | columns
+# ```
+# ```
+# ╭────┬───────────╮
+# │  0 │ name      │
+# │  1 │ branch    │
+# │  2 │ remote    │
+# │  3 │ tag       │
+# │  4 │ index     │
+# │  5 │ ignored   │
+# │  6 │ conflicts │
+# │  7 │ ahead     │
+# │  8 │ behind    │
+# │  9 │ worktree  │
+# │ 10 │ stashes   │
+# │ 11 │ clean     │
+# ╰────┴───────────╯
+# ```
 export def "gm report" []: nothing -> table<name: string, branch: string, remote: string, tag: string, index: int, ignored: int, conflicts: int, ahead: int, behind: int, worktree: int, stashes: int, clean: bool> {
     if (which gstat | is-empty) {
         error make --unspanned {
diff --git a/src/nu-git-manager-sugar/git/mod.nu b/src/nu-git-manager-sugar/git/mod.nu
index a0d2de51..00f2e243 100644
--- a/src/nu-git-manager-sugar/git/mod.nu
+++ b/src/nu-git-manager-sugar/git/mod.nu
@@ -6,12 +6,16 @@ use ../completions/nu-complete.nu [GIT_QUERY_TABLES, git-query-tables]
 
 # get the commit hash of any revision
 #
-# # Examples
-#     get the commit hash of the currently checked out revision
-#     > gm repo get commit
-#
-#     get the commit hash of the main branch
-#     > gm repo get commit main
+# ## Examples
+# ```nushell
+# # get the commit hash of the currently checked out revision
+# gm repo get commit
+# ```
+# ---
+# ```nushell
+# # get the commit hash of the main branch
+# gm repo get commit main
+# ```
 export def "gm repo get commit" [
     revision: string = "HEAD"  # the revision to get the hash of
 ]: nothing -> string {
@@ -22,20 +26,24 @@ export def "gm repo get commit" [
 export def "gm repo compare" [
     target: string, # the target to compare from
     --head: string = "HEAD", # the "head" to use for the comparison
-] {
+]: nothing -> string {
     ^git diff (^git merge-base $target $head) $head
 }
 
-def repo-root [] {
+def repo-root []: nothing -> string {
     ^git rev-parse --show-toplevel
 }
 
 # go to the root of the repository from anywhere in the worktree
 #
-# # Examples
-#     go back to the root of a repo
-#     > cd foo/bar/baz; gm repo goto root; print (pwd)
-#     /path/to/repo
+# ## Examples
+# ```nushell
+# # go back to the root of a repo
+# cd foo/bar/baz; gm repo goto root; print (pwd)
+# ```
+# ```
+# /path/to/repo
+# ```
 export def --env "gm repo goto root" []: nothing -> nothing {
     cd (repo-root)
 }
@@ -46,12 +54,16 @@ export def --env "gm repo goto root" []: nothing -> nothing {
 # > in the following, a "*dangling*" branch refers to a branch that does not have any remote
 # > counterpart, i.e. it's a purely local branch.
 #
-# # Examples
-#     list branches and their associated remotes
-#     > gm repo branches
-#
-#     clean all dangling branches
-#     > gm repo branches --clean
+# ## Examples
+# ```nushell
+# # list branches and their associated remotes
+# gm repo branches
+# ```
+# ---
+# ```nushell
+# # clean all dangling branches
+# gm repo branches --clean
+# ```
 export def "gm repo branches" [
     --clean  # clean all dangling branches
 ]: nothing -> table<branch: string, remotes: list<string>> {
@@ -93,7 +105,7 @@ export def "gm repo branches" [
 export def "gm repo branch wipe" [
     branch: string, # the branch to wipe
     remote: string, # the remote to push to
-] {
+]: nothing -> nothing {
     ^git branch --delete --force $branch
     ^git push $remote --delete $branch
 }
@@ -101,14 +113,22 @@ export def "gm repo branch wipe" [
 
 # return true iif the first revision is an ancestor of the second
 #
-# # Examples
-#     HEAD~20 is an ancestor of HEAD
-#     > gm repo is-ancestor HEAD~20 HEAD
-#     true
-#
-#     HEAD is never an ancestor of HEAD~20
-#     > gm repo is-ancestor HEAD HEAD~20
-#     false
+# ## Examples
+# ```nushell
+# # HEAD~20 is an ancestor of HEAD
+# gm repo is-ancestor HEAD~20 HEAD
+# ```
+# ```
+# true
+# ```
+# ---
+# ```nushell
+# # HEAD is never an ancestor of HEAD~20
+# gm repo is-ancestor HEAD HEAD~20
+# ```
+# ```
+# false
+# ```
 export def "gm repo is-ancestor" [
     a: string  # the base commit-ish revision
     b: string  # the *head* commit-ish revision
@@ -117,12 +137,17 @@ export def "gm repo is-ancestor" [
 }
 
 # get the list of all the remotes in the current repository
-# # Examples
-#     list all the remotes in a default `nu-git-manager` repo
-#     > gm repo remote list
-#     #┬remote┬──────────────────fetch──────────────────┬─────────────────push──────────────────
-#     0│origin│https://github.com/amtoine/nu-git-manager│ssh://github.com/amtoine/nu-git-manager
-#     ─┴──────┴─────────────────────────────────────────┴───────────────────────────────────────
+#
+# ## Examples
+# ```nushell
+# # list all the remotes in a default `nu-git-manager` repo
+# gm repo remote list
+# ```
+# ```
+# #┬remote┬──────────────────fetch──────────────────┬─────────────────push──────────────────
+# 0│origin│https://github.com/amtoine/nu-git-manager│ssh://github.com/amtoine/nu-git-manager
+# ─┴──────┴─────────────────────────────────────────┴───────────────────────────────────────
+# ```
 export def "gm repo remote list" []: nothing -> table<remote: string, fetch: string, push: string> {
     # FIXME: use the helper `list-remotes` command from ../nu-git-manager/git/repo.nu:29
     ^git remote --verbose
@@ -142,7 +167,7 @@ export def "gm repo fetch branch" [
     remote: string, # the branch to fetch
     branch: string, # the remote to fetch the branch from
     --strategy: string = "none" # the merge strategy to use
-] {
+]: nothing -> nothing {
     ^git fetch $remote $branch
 
     if (^git branch --list | lines | str substring 2.. | where $it == $branch | is-empty) {
@@ -190,7 +215,7 @@ def get-branches [--merged, --no-merged]: nothing -> list<string> {
 }
 
 # remove a branch interactively
-export def "gm repo branch interactive-delete" [] {
+export def "gm repo branch interactive-delete" []: nothing -> nothing {
     let choice = get-branches | input list --multi "remove"
     if ($choice | is-empty) {
         return
@@ -260,7 +285,30 @@ export def "gm repo ls" [
     }
 }
 
-# TODO: documentation
+# queries the `.git/` directory as a database with `nu_plugin_git_query`
+#
+# ## Examples
+# ```nushell
+# # get the commits of the current repo
+# gm repo query commits
+# ```
+# ---
+# ```nushell
+# # get the total number of insertions and deletions per author
+# gm repo query diffs
+#     | group-by name
+#     | transpose author data
+#     | insert insertions { get data.insertions | math sum }
+#     | insert deletions { get data.deletions | math sum }
+#     | reject data
+# ```
+# ```
+# #┬────author────┬insertions┬deletions
+# 0│amtoine       │      6770│     5402
+# 1│Antoine Stevan│      8537│     4562
+# 2│Mel Massadian │       654│       64
+# ─┴──────────────┴──────────┴─────────
+# ```
 export def "gm repo query" [table: string@git-query-tables]: nothing -> table {
     if $table not-in $GIT_QUERY_TABLES {
         error make {
diff --git a/src/nu-git-manager-sugar/git/prompt.nu b/src/nu-git-manager-sugar/git/prompt.nu
index 14d08f87..2b7bb029 100644
--- a/src/nu-git-manager-sugar/git/prompt.nu
+++ b/src/nu-git-manager-sugar/git/prompt.nu
@@ -8,33 +8,61 @@ const DEFAULT_PROMPT_INDICATORS = {
 # setup the Git prompt of NGM
 #
 # the different sections of the prompt are the following, in order and separated by a single space:
-# - "admin_segment": shows if you are an admin of the session
-# - "pwd": shows the current working directory, in long form outside of a repo or with only the
+# - "_admin_": shows if you are an admin of the session
+# - "_pwd_": shows the current working directory, in long form outside of a repo or with only the
 #     basename if inside a Git repo
-# - "git_branch_segment": if inside a Git repo, will show the current branch, the tag or the
+# - "_Git branch_": if inside a Git repo, will show the current branch, the tag or the
 #     detached revision
-# - "git_action_segment": if inside a Git repo and performing a Git action, such as a MERGE or a
+# - "_Git action_": if inside a Git repo and performing a Git action, such as a MERGE or a
 #     REBASE, the prompt will show the stage of the action
-# - "duration_segment": if the last command took longer than the `--duration-threshold`, the prompt
+# - "_duration_": if the last command took longer than the `--duration-threshold`, the prompt
 #     will show the exact duration
-# - "command_failed_segment": if the last command failed, the exit code will be shown
-# - "login_segment": shows if you are in a login session
+# - "_command failed_": if the last command failed, the exit code will be shown
+# - "_login_": shows if you are in a login session
 #
-# # Examples
-#     setup the prompt with 10sec of command duration and `> ` as the Vi indicator
-#     > export-env {
-#           use nu-git-manager-sugar git-prompt setup
-#           setup --duration-threshold 10sec --indicators {
-#               vi: {
-#                   insert: "> "
-#                   normal: "> "
-#               }
-#           }
-#       }
+# ## the look
+# - outside of a Git repo
+# ```
+# ~/documents/repos/github.com >
+# ```
+# - on a branch
+# ```
+# nu-git-manager (main:c2242b4) >
+# ```
+# - with the `HEAD` detached
+# ```
+# nu-git-manager (_:adca8cb) >
+# ```
+# - on a tag
+# ```
+# nu-git-manager (0.3.0:3fb5c89) >
+# ```
+# - during a rebase
+# ```
+# nu-git-manager (_:5d8245d) (REBASE-i) >
+# ```
+# - inside a subdirectory
+# ```
+# nu-git-manager/src/nu-git-manager (main:c2242b4) >
+# ```
+#
+# ## Examples
+# ```nushell
+# # setup the prompt with 10sec of command duration and `> ` as the Vi indicator
+# export-env {
+#     use nu-git-manager-sugar git-prompt setup
+#     setup --duration-threshold 10sec --indicators {
+#         vi: {
+#             insert: "> "
+#             normal: "> "
+#         }
+#     }
+# }
+# ```
 export def --env setup [
     --indicators = $DEFAULT_PROMPT_INDICATORS,
     --duration-threshold: duration = 1sec  # the threshold above which the command duration is shown
-] {
+]: nothing -> nothing {
     $env.PROMPT_COMMAND = { get-left-prompt $duration_threshold }
     $env.PROMPT_COMMAND_RIGHT = ""
 
diff --git a/src/nu-git-manager-sugar/github.nu b/src/nu-git-manager-sugar/github.nu
index 657ba78d..d1ac0cbb 100644
--- a/src/nu-git-manager-sugar/github.nu
+++ b/src/nu-git-manager-sugar/github.nu
@@ -63,17 +63,23 @@ def "warning make" [
 # > see the [rest API of GitHub](https://docs.github.com/en/rest) for a complete
 # > list of available end points and documentation
 #
-# # Examples
-#     list the releases of Nushell sorted by date
-#     > gm gh query-api "/repos/nushell/nushell/releases"
-#           | select tag_name published_at
-#           | rename tag date
-#           | into datetime date
-#           | sort-by date
-#
-#     get the bio of @amtoine
-#     > gm gh query-api --no-paginate "/users/amtoine" | get bio
-#     you shall not rebase in the middle of a PR review nor close other's review threads :pray:
+# ## Examples
+# ```nushell
+# # list the releases of Nushell sorted by date
+# gm gh query-api "/repos/nushell/nushell/releases"
+#     | select tag_name published_at
+#     | rename tag date
+#     | into datetime date
+#     | sort-by date
+# ```
+# ---
+# ```nushell
+# # get the bio of @amtoine
+# gm gh query-api --no-paginate "/users/amtoine" | get bio
+# ```
+# ```
+# you shall not rebase in the middle of a PR review nor close other's review threads :pray:
+# ```
 export def "gm gh query-api" [
     end_point: string # the end point in the GitHub API to query
     --page-size: int = 100 # the size of each page
@@ -170,13 +176,15 @@ export def "gm gh query-api" [
 
 # list the releases of a GitHub repository
 #
-# # Examples
-#     get the last release of the `github.com:nushell/nushell` repository
-#     > gm gh query-releases "nushell/nushell"
-#           | into datetime published_at
-#           | sort-by published_at
-#           | last
-#           | select tag_name published_at
+# ## Examples
+# ```nushell
+# # get the last release of the `github.com:nushell/nushell` repository
+# gm gh query-releases "nushell/nushell"
+#     | into datetime published_at
+#     | sort-by published_at
+#     | last
+#     | select tag_name published_at
+# ```
 export def "gm gh query-releases" [
     repo: string # the GitHub repository to query the releases of
     --page-size: int = 100 # the size of each page
@@ -187,9 +195,11 @@ export def "gm gh query-releases" [
 
 # get information about a GitHub user
 #
-# Examples:
-#     get the avatar picture of @amtoine
-#     > gm gh query-user amtoine | get avatar_url | http get $in | save --force amtoine.png
+# ## Examples:
+# ```nushell
+# # get the avatar picture of @amtoine
+# gm gh query-user amtoine | get avatar_url | http get $in | save --force amtoine.png
+# ```
 export def "gm gh query-user" [
     user: string # the user to query information about
     --no-gh # force to use `http get` instead of `gh`
@@ -198,7 +208,7 @@ export def "gm gh query-user" [
 }
 
 # checkout one of the repo's PR interactively
-export def "gm gh pr checkout" [] {
+export def "gm gh pr checkout" []: nothing -> nothing {
     if (which gh --all | where type == external | is-empty) {
         error make --unspanned {
             msg: (
diff --git a/src/nu-git-manager/mod.nu b/src/nu-git-manager/mod.nu
index dbd5b74f..3c00f714 100644
--- a/src/nu-git-manager/mod.nu
+++ b/src/nu-git-manager/mod.nu
@@ -13,30 +13,40 @@ use error/error.nu [throw-error, throw-warning]
 
 use completions/nu-complete.nu
 
-# manage your Git repositories with the main command of `nu-git-manager`
+# manage your Git repositories with the main command of NGM
 #
-# `nu-git-manager` will look for a store in the following places, in order:
+# ### the location for the store
+# NGM will look for a store in the following places, in order:
 # - `$env.GIT_REPOS_HOME`
-# - `$env.XDG_DATA_HOME | path join "repos"
+# - `$env.XDG_DATA_HOME | path join "repos"`
 # - `~/.local/share/repos`
 #
-# `nu-git-manager` will look for a cache in the following places, in order:
+# ### the cache
+# NGM will look for a cache in the following places, in order:
 # - `$env.GIT_REPOS_CACHE`
-# - `$env.XDG_CACHE_HOME | path join "nu-git-manager/cache.nuon"
+# - `$env.XDG_CACHE_HOME | path join "nu-git-manager/cache.nuon"`
 # - `~/.cache/nu-git-manager/cache.nuon`
 #
-# # Examples
-#     a contrived example to set the path to the root of the store
-#     > with-env { GIT_REPOS_HOME: ($nu.home-path | path join "foo") } {
-#           gm status | get root.path | str replace $nu.home-path '~'
-#       }
-#     ~/foo
-#
-#     a contrived example to set the path to the cache of the store
-#     > with-env { XDG_CACHE_HOME: ($nu.home-path | path join "foo") } {
-#           gm status | get cache.path | str replace $nu.home-path '~'
-#       }
-#     ~/foo/nu-git-manager/cache.nuon
+# ## Examples
+# ```nushell
+# # a contrived example to set the path to the root of the store
+# with-env { GIT_REPOS_HOME: ($nu.home-path | path join "foo") } {
+#     gm status | get root.path | str replace $nu.home-path '~'
+# }
+# ```
+# ```
+# ~/foo
+# ```
+# ---
+# ```nushell
+# # a contrived example to set the path to the cache of the store
+# with-env { XDG_CACHE_HOME: ($nu.home-path | path join "foo") } {
+#     gm status | get cache.path | str replace $nu.home-path '~'
+# }
+# ```
+# ```
+# ~/foo/nu-git-manager/cache.nuon
+# ```
 export def "gm" []: nothing -> nothing {
     print (help gm)
 }
@@ -45,21 +55,31 @@ export def "gm" []: nothing -> nothing {
 #
 # will give a nice error if the repository is already in the local store.
 #
-# # Examples
-#     clone a repository in the local store of `nu-git-manager`
-#     > gm clone https://github.com/amtoine/nu-git-manager
-#
-#     clone as a bare repository, i.e. a repo without a worktree
-#     > gm clone --bare https://github.com/amtoine/nu-git-manager
-#
-#     clone a repo and change the name of the remote
-#     > gm clone --remote default https://github.com/amtoine/nu-git-manager
-#
-#     setup a public repo in the local store and use HTTP to fetch without PAT and push with SSH
-#     > gm clone https://github.com/amtoine/nu-git-manager --fetch https --push ssh
-#
-#     clone a big repo as a single commit, avoiding all intermediate Git deltas
-#     > gm clone https://github.com/neovim/neovim --depth 1
+# ## Examples
+# ```nushell
+# # clone a repository in the local store of `nu-git-manager`
+# gm clone https://github.com/amtoine/nu-git-manager
+# ```
+# ---
+# ```nushell
+# # clone as a bare repository, i.e. a repo without a worktree
+# gm clone --bare https://github.com/amtoine/nu-git-manager
+# ```
+# ---
+# ```nushell
+# # clone a repo and change the name of the remote
+# gm clone --remote default https://github.com/amtoine/nu-git-manager
+# ```
+# ---
+# ```nushell
+# # setup a public repo in the local store and use HTTP to fetch without PAT and push with SSH
+# gm clone https://github.com/amtoine/nu-git-manager --fetch https --push ssh
+# ```
+# ---
+# ```nushell
+# # clone a big repo as a single commit, avoiding all intermediate Git deltas
+# gm clone https://github.com/neovim/neovim --depth 1
+# ```
 export def "gm clone" [
     url: string # the URL to the repository to clone, supports HTTPS and SSH links, as well as references ending in `.git` or starting with `git@`
     --remote: string = "origin" # the name of the remote to setup
@@ -171,17 +191,23 @@ export def "gm clone" [
 
 # list all the local repositories in your local store
 #
-# /!\ this command will return sanitized paths. /!\
-#
-# # Examples
-#     list all the repositories in the store
-#     > gm list
-#
-#     list all the repositories in the store with their full paths
-#     > gm list --full-path
-#
-#     jump to a directory in the store
-#     > cd (gm list --full-path | input list)
+# **/!\\** this command will return sanitized paths. **/!\\**
+#
+# ## Examples
+# ```nushell
+# # list all the repositories in the store
+# gm list
+# ```
+# ---
+# ```nushell
+# # list all the repositories in the store with their full paths
+# gm list --full-path
+# ```
+# ---
+# ```nushell
+# # jump to a directory in the store
+# cd (gm list --full-path | input list)
+# ```
 export def "gm list" [
     --full-path # show the full path instead of only the "owner + group + repo" name
 ]: nothing -> list<path> {
@@ -195,43 +221,61 @@ export def "gm list" [
     }
 }
 
-# get current status about the repositories managed by `nu-git-manager`
-#
-# /!\ `$.root.path` and `$.cache.path` will be sanitized /!\
-#
-# Examples
-#     getting status when everything is fine
-#     > gm status | reject missing | flatten | into record
-#     ╭─────────────────────┬────────────────────────────────────╮
-#     │ path                │ ~/.local/share/repos               │
-#     │ exists              │ true                               │
-#     │ cache_path          │ ~/.cache/nu-git-manager/cache.nuon │
-#     │ cache_exists        │ true                               │
-#     │ should_update_cache │ false                              │
-#     ╰─────────────────────┴────────────────────────────────────╯
-#
-#     getting status when there is no store
-#     > gm status | get root
-#     ╭────────┬──────────────────────╮
-#     │ path   │ ~/.local/share/repos │
-#     │ exists │ false                │
-#     ╰────────┴──────────────────────╯
-#
-#     getting status when there is no cache
-#     > gm status | get root
-#     ╭────────┬────────────────────────────────────╮
-#     │ path   │ ~/.cache/nu-git-manager/cache.nuon │
-#     │ exists │ false                              │
-#     ╰────────┴────────────────────────────────────╯
-#
-#     getting status when a project is in the cache but is missing on the filesystem
-#     > gm status | get missing
-#     ╭──────────────────────────────────────╮
-#     │ 0 │ ~/.local/share/repos/foo/bar/baz │
-#     ╰──────────────────────────────────────╯
-#
-#     update the cache if necessary
-#     > if (gm status).should_update_cache { gm update-cache }
+# get current status about the repositories managed by NGM
+#
+# **/!\\** `$.root.path` and `$.cache.path` will be sanitized **/!\\**
+#
+# ## Examples
+# ```nushell
+# # getting status when everything is fine
+# gm status | reject missing | flatten | into record
+# ```
+# ```
+# ╭─────────────────────┬────────────────────────────────────╮
+# │ path                │ ~/.local/share/repos               │
+# │ exists              │ true                               │
+# │ cache_path          │ ~/.cache/nu-git-manager/cache.nuon │
+# │ cache_exists        │ true                               │
+# │ should_update_cache │ false                              │
+# ╰─────────────────────┴────────────────────────────────────╯
+# ```
+# ---
+# ```nushell
+# # getting status when there is no store
+# gm status | get root
+# ```
+# ```
+# ╭────────┬──────────────────────╮
+# │ path   │ ~/.local/share/repos │
+# │ exists │ false                │
+# ╰────────┴──────────────────────╯
+# ```
+# ---
+# ```nushell
+# # getting status when there is no cache
+# gm status | get root
+# ```
+# ```
+# ╭────────┬────────────────────────────────────╮
+# │ path   │ ~/.cache/nu-git-manager/cache.nuon │
+# │ exists │ false                              │
+# ╰────────┴────────────────────────────────────╯
+# ```
+# ---
+# ```nushell
+# # getting status when a project is in the cache but is missing on the filesystem
+# gm status | get missing
+# ```
+# ```
+# ╭──────────────────────────────────────╮
+# │ 0 │ ~/.local/share/repos/foo/bar/baz │
+# ╰──────────────────────────────────────╯
+# ```
+# ---
+# ```nushell
+# # update the cache if necessary
+# if (gm status).should_update_cache { gm update-cache }
+# ```
 export def "gm status" []: nothing -> record<root: record<path: path, exists: bool>, missing: list<path>, cache: record<path: path, exists: bool>, should_update_cache: bool> {
     let root = get-repo-store-path
     let cache = get-repo-store-cache-path
@@ -260,9 +304,11 @@ export def "gm status" []: nothing -> record<root: record<path: path, exists: bo
 
 # update the local cache of repositories
 #
-# # Examples
-#     update the cache of repositories
-#     > gm update-cache
+# ## Examples
+# ```nushell
+# # update the cache of repositories
+# gm update-cache
+# ```
 export def "gm update-cache" []: nothing -> nothing {
     let cache_file = get-repo-store-cache-path
     clean-cache-dir $cache_file
@@ -280,18 +326,26 @@ export def "gm update-cache" []: nothing -> nothing {
 
 # remove one of the repositories from your local store
 #
-# # Examples
-#     remove any repository by fuzzy-finding the whole store
-#     > gm remove --fuzzy
-#
-#     restrict the search to any one of my repositories
-#     > gm remove amtoine
-#
-#     remove a precise repo by giving its full name, a name collision is unlikely
-#     > gm remove amtoine/nu-git-manager
-#
-#     remove a precise repo without confirmation
-#     > gm remove amtoine/nu-git-manager --no-confirm
+# ## Examples
+# ```nushell
+# # remove any repository by fuzzy-finding the whole store
+# gm remove --fuzzy
+# ```
+# ---
+# ```nushell
+# # restrict the search to any one of my repositories
+# gm remove amtoine
+# ```
+# ---
+# ```nushell
+# # remove a precise repo by giving its full name, a name collision is unlikely
+# gm remove amtoine/nu-git-manager
+# ```
+# ---
+# ```nushell
+# # remove a precise repo without confirmation
+# gm remove amtoine/nu-git-manager --no-confirm
+# ```
 export def "gm remove" [
     pattern?: string # a pattern to restrict the choices
     --fuzzy # remove after fuzzy-finding the repo(s) to clean
@@ -400,15 +454,19 @@ export def "gm remove" [
 # - keys: the root hash of repos, e.g. [2ed2d87](https://github.com/amtoine/nu-git-manager/commit/2ed2d875d80505d78423328c6b2a60522715fcdf) for `nu-git-manager`
 # - values: the main fork to select in full-name form, e.g. `github.com/amtoine/nu-git-manager`
 #
-# # Examples
-#     squash forks interactively
-#     > gm squash-forks
-#
-#     squash forks non-interactively: `nu-git-manager` and `nushell` to the forks of @amtoine
-#     > gm squash-forks --non-interactive-preselect {
-#           2ed2d875d80505d78423328c6b2a60522715fcdf: "github.com/amtoine/nu-git-manager",
-#           8f3b273337b53bd86d5594d5edc9d4ad7242bd4c: "github.com/amtoine/nushell",
-#       }
+# ## Examples
+# ```nushell
+# # squash forks interactively
+# gm squash-forks
+# ```
+# ---
+# ```nushell
+# # squash forks non-interactively: `nu-git-manager` and `nushell` to the forks of @amtoine
+# gm squash-forks --non-interactive-preselect {
+#     2ed2d875d80505d78423328c6b2a60522715fcdf: "github.com/amtoine/nu-git-manager",
+#     8f3b273337b53bd86d5594d5edc9d4ad7242bd4c: "github.com/amtoine/nushell",
+# }
+# ```
 export def "gm squash-forks" [
     --non-interactive-preselect: record = {} # the non-interactive preselection record, see documentation above
 ]: nothing -> nothing {
@@ -474,14 +532,18 @@ export def "gm squash-forks" [
 #
 # this command will mainly remove empty directory recursively.
 #
-# /!\ this command will return sanitized paths. /!\
-#
-# Examples
-#     clean the store
-#     > gm clean
-#
-#     list the leaves of the store that would have to be cleaned
-#     > gm clean --list
+# **/!\\** this command will return sanitized paths. **/!\\**
+#
+# ## Examples
+# ```nushell
+# # clean the store
+# gm clean
+# ```
+# ---
+# ```nushell
+# # list the leaves of the store that would have to be cleaned
+# gm clean --list
+# ```
 export def "gm clean" [
     --list # only list without cleaning
 ]: nothing -> list<path> {
diff --git a/toolkit.nu b/toolkit.nu
index 6f858581..3b7e2374 100644
--- a/toolkit.nu
+++ b/toolkit.nu
@@ -161,8 +161,7 @@ def document-command [
     let signatures = $help.signatures | transpose | get column1
 
     let page = [
-        $"# `($args.module_name) ($command)`",
-        $"## Description",
+        $"# `($command)` \(`($args.module_name)`\)",
         $help.usage,
         "",
         $help.extra_usage,