diff --git a/doc/comp.md b/doc/comp.md
index 6bb48005..8543c01a 100644
--- a/doc/comp.md
+++ b/doc/comp.md
@@ -1,4 +1,8 @@
-# Custom Component
+---
+title: Custom Components
+---
+
+# Custom Components
 
 Kaboom uses a flexible component system that helps you compose game logic.
 
diff --git a/doc/dev.md b/doc/dev.md
index 444a0b4f..825b82f1 100644
--- a/doc/dev.md
+++ b/doc/dev.md
@@ -1,3 +1,7 @@
+---
+title: Contributing
+---
+
 # Developing Kaboom
 
 To start developing Kaboom, first clone the github repo
@@ -36,6 +40,3 @@ $ npm run check
 - `scripts/` development scripts
 - `sprites/` some examples sprites
 - `src/` kaboom library source code
-## Source code overview
-
-(todo)
diff --git a/doc/intro.md b/doc/intro.md
index 3d450baa..9a9f6447 100644
--- a/doc/intro.md
+++ b/doc/intro.md
@@ -1,3 +1,7 @@
+---
+title: Getting started
+---
+
 # Intro to Kaboom
 
 Welcome! Kaboom is a JavaScript library that helps you make games fast and fun :D
diff --git a/doc/migration-3000.md b/doc/migration-3000.md
index 87e9eeec..00b54924 100644
--- a/doc/migration-3000.md
+++ b/doc/migration-3000.md
@@ -1,3 +1,7 @@
+---
+title: Migratin from v2000 to v3000
+---
+
 # Migrating from v2000 to v3000
 
 - `obj._id` is renamed to `obj.id`
diff --git a/doc/publishing.md b/doc/publishing.md
index ef2e8f7c..c4fad2f0 100644
--- a/doc/publishing.md
+++ b/doc/publishing.md
@@ -1,3 +1,7 @@
+---
+title: Publishing
+---
+
 # Publishing a Kaboom game
 When we finish our game, the most important time it's here...
 Publish it! 
diff --git a/doc/setup.md b/doc/setup.md
index 9f54e62e..da10cc5b 100644
--- a/doc/setup.md
+++ b/doc/setup.md
@@ -1,27 +1,33 @@
-# Setting up Kaboom Development
+---
+title: Installation
+---
 
-## Using `create-kaboom` to generate kaboom project
+# Installation
+
+The most easy way to get started with Kaboom is to use the [CLI tool](https://www.npmjs.com/package/create-kaboom), which will generate a Kaboom project for you:
 
 ```sh
 $ npm init kaboom -- mygame
+$ cd mygame
+$ npm run dev
 ```
 
-This will create a directory `mygame` containing everything you need to start a Kaboom project, go to that directory and run `npm run dev` to start the development server, and edit `src/main.js` to develop the game.
+This will create your game in the `mygame` directory, and start a development server for you to preview your game. If you edit `src/main.js` and refresh the page, you will see your changes.
 
-to see all options, run
+To see all options, run:
 
 ```sh
 $ npm init kaboom -- --help
 ```
 
-## Using CDN
+## Using a CDN
 
 Getting the package from a CDN provider is the quickest and easiest way to start using Kaboom.
 
 ```html
 <script type="module">
 
-// import kaboom lib
+// import kaboom.js
 import kaboom from "https://unpkg.com/kaboom@3000.0.1/dist/kaboom.mjs";
 
 // initialize kaboom context
@@ -38,23 +44,33 @@ add([
 
 You can paste this directly in a `.html` file and open with the browser. This will give you the standard fullscreen Kaboom canvas. Feel free to put more HTML in there.
 
-The Kaboom package is deployed to NPM, so it's availbale on various CDN providers, like `unpkg`, `skypack`, `jsdelivr`, etc.
-
-The example above is using Kaboom with es6 module, you can also just include it with a `<script>` tag
+The Kaboom package is deployed to npm, so it's availbale on various CDN providers, like `unpkg`, `skypack`, `jsdelivr`, etc.
 
+You can also just include it with a `<script>` tag.
 ```html
 <script src="https://unpkg.com/kaboom@3000.0.1/dist/kaboom.js"></script>
+
+<script>
+    kaboom();
+</script>
 ```
 
-## Using NPM
+## Setup your own Node.js environment
 
-With NPM it's easier have some other packages and do version control, also it's easier to get typescript autocomplete support and stuff, but it requires a bit more setup.
+With Node.js and npm it's easier have some other packages and use version control, also it's easier to get typescript autocomplete support, but it requires a bit more setup. (This is the way of `create-kaboom`)
 
 ```sh
 $ npm install kaboom
 ```
 
-but you'll need to use a bundler to use Kaboom with NPM. There's a lot of options like `esbuild`, `webpack`, `parcel`, `vite`, etc, here I'll give a short example of how to use Kaboom with [`esbuild`](https://esbuild.github.io/).
+You'll need to use a bundler to use Kaboom with NPM. There's a lot of options like:
+
+- `esbuild`, 
+- `webpack`,
+- `parcel`, 
+- `vitejs`,
+
+This is a short example of how to use Kaboom with ["esbuild"](https://esbuild.github.io/).
 
 Once you have `esbuild` installed, and you have this in a `.js` or `.ts` file:
 
diff --git a/doc/shader.md b/doc/shader.md
deleted file mode 100644
index afc960a5..00000000
--- a/doc/shader.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# Custom Shaders
-
-(todo)
diff --git a/doc/tips.md b/doc/tips.md
index cc2b4d51..026f7da9 100644
--- a/doc/tips.md
+++ b/doc/tips.md
@@ -1,4 +1,8 @@
-# Tips
+---
+title: Optimization
+---
+
+# Optimization Tips
 
 Here's some tips on optimizing performance / maintainability for kaboom games