diff --git a/docs/examples.md b/docs/examples.md
new file mode 100644
index 0000000..633bad1
--- /dev/null
+++ b/docs/examples.md
@@ -0,0 +1,9 @@
+# Examples
+
+DevShell is used in these projects, feel free to take inspiration from them:
+
+- [nix-gitlab-ci (only V3)](https://gitlab.com/TECHNOFAB/nix-gitlab-ci)
+- [soonix](https://gitlab.com/TECHNOFAB/soonix)
+- [rensa-core](https://gitlab.com/rensa-nix/core)
+- [rensa-devtools](https://gitlab.com/rensa-nix/devtools)
+
diff --git a/docs/index.md b/docs/index.md
index ea5eeb1..34a1810 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1 +1,15 @@
-# Hello world!
+# Rensa DevShell
+
+Minimal devshell implementation using Modules.
+Inspired by [numtide/devshell](https://github.com/numtide/devshell).
+
+It features the absolute basics, like env variables (dynamic values/eval supported),
+programs and shell hooks ([`enterShellCommands`](./options.md#entershellcommands)).
+Additional functionality can be added with modules, like [Rensa DevTools](https://devtools.rensa.projects.tf).
+
+## Features
+
+- **fast**: due to the NixOS module system it's a bit slower than `pkgs.mkShell`, but only about 10% (still in the tens of milliseconds range)
+- **minimal**: only contains the bare minimum, the rest should be added with imported modules
+- **straight forward**: no toml (like numtide/devshell), no abstractions over Nix (like devenv), just a straight forward Nix lib
+
diff --git a/docs/integrations.md b/docs/integrations.md
new file mode 100644
index 0000000..edec754
--- /dev/null
+++ b/docs/integrations.md
@@ -0,0 +1,5 @@
+# Integrations / Modules
+
+- [soonix](https://soonix.projects.tf/usage/#with-devshell)
+- [rensa devtools](https://devtools.rensa.projects.tf)
+
diff --git a/docs/usage.md b/docs/usage.md
new file mode 100644
index 0000000..0c8fb83
--- /dev/null
+++ b/docs/usage.md
@@ -0,0 +1,80 @@
+# Usage
+
+## Basic Shell
+
+The absolute minimum to get started:
+
+```nix
+devshell.mkShell {}
+```
+
+That's it. You've got yourself a shell. Not very exciting, but it works.
+
+## Adding Packages
+
+Want some tools? Throw them in:
+
+```nix
+devshell.mkShell {
+  packages = [ pkgs.hello pkgs.git pkgs.nodejs ];
+}
+```
+
+## Environment Variables
+
+Set some env vars (because who doesn't love those):
+
+```nix
+devshell.mkShell {
+  env = {
+    HELLO.value = "world";
+  };
+}
+```
+
+## Shell Hooks
+
+Run stuff when entering the shell:
+
+```nix
+devshell.mkShell {
+  enterShellCommands."hello".text = ''
+    echo "Welcome to the devshell!"
+    echo "Current directory: $PWD"
+  '';
+}
+```
+
+## Putting It All Together
+
+A more realistic example:
+
+```nix
+devshell.mkShell {
+  packages = [ pkgs.nodejs pkgs.yarn pkgs.git ];
+  
+  env = {
+    NODE_ENV.value = "development";
+    API_URL.value = "http://localhost:3000";
+  };
+  
+  enterShellCommands."enter".text = ''
+    echo "🚀 Development environment ready!"
+    node --version
+  '';
+}
+```
+
+## Need More Features?
+
+For additional functionality, import modules:
+
+```nix
+devshell.mkShell {
+  imports = [ some-module.devshellModule ];
+  # your config...
+}
+```
+
+Check out [available modules](./integrations.md) for things like automatic file
+generation, dev tools and more.
diff --git a/nix/repo/docs.nix b/nix/repo/docs.nix
index c9cb95d..9af135b 100644
--- a/nix/repo/docs.nix
+++ b/nix/repo/docs.nix
@@ -47,6 +47,9 @@ in
         };
         nav = [
           {"Introduction" = "index.md";}
+          {"Usage" = "usage.md";}
+          {"Integrations" = "integrations.md";}
+          {"Examples" = "examples.md";}
           {"Options" = "options.md";}
         ];
         markdown_extensions = [