1 files changed, 52 insertions, 0 deletions
diff --git a/README.md b/README.md
index 7d5a5f76..ff124b2e 100644
--- a/README.md
+++ b/README.md
@@ -424,3 +424,55 @@ I'm happy to accept code contributions from anyone who has a bug fix, new featur
 If you would like to contact me directly, you can find my e-mail address on my
 [Github profile page](https://github.com/bhilburn).
 
+#### Developers Guide
+
+The theme has grown a lot lately, so I think a little explanation would be 
+helpful.
+
+##### Basic Knowledge
+
+Our main entry point are the `PROMPT` and `RPROMPT` variables, which are 
+interpreted by zsh itself. All that this (and any other) theme does is
+filling these two variables with control instructions (like defining 
+colors, etc.) and ready-to-use data. So within this theme we collect a
+whole bunch of information to put in that variables. You can find 
+`PROMPT` and `RPROMPT` at the very end of the `powerlevel9k.zsh-theme`.
+
+This simple diagram may explain the invoking order better:
+
+```
++-----+    +---------+
+| Zsh |--->| $PROMPT |
++-----+    +---------+
+                |
+                V
+    +---------------------+    +------------+  +---------------------+
+    | build_left_prompt() |--->| prompt_*() |->| $1_prompt_segment() |
+    +---------------------+    +------------+  +---------------------+
+```
+
+##### Adding Segments
+
+Feel free to add your own segments. Every segment gets called with an
+orientation as first parameter (`left` or `right`), so we can figure
+out on which side we should draw the segment. This information is 
+used at the time we call the actual segment-drawing function:
+`$1_prompt_segment`. To make the magic color-overwrite mechanism to
+work, we have to pass our function name as first argument. Usually
+this is just `$0`. Second parameter is a default background color,
+third the default foreground color. And finally we pass our content
+to the function. So our function could look somewhat like this:
+
+```zsh
+    prompt_echo() {
+        local content='Hello World!'
+        $1_prompt_segment $0 blue red $content
+    }
+```
+
+At this point we can overwrite our blue-on-red segment by putting 
+    
+    POWERLEVEL9K_ECHO_FOREGROUND="200"
+    POWERLEVEL9K_ECHO_BACKGROUND="040"
+
+in our `~/.zshrc`. We now have a pink-on-green segment. Yay!