diff --git a/Readme.md b/Readme.md
index 8897212b..0841f109 100644
--- a/Readme.md
+++ b/Readme.md
@@ -35,6 +35,37 @@ Ace is a community project. We actively encourage and support contributions. The
     git clone git://github.com/ajaxorg/ace.git
     git submodule update --init --recursive
 
+Embedding Ace
+-------------
+
+Ace can be easily embedded into any existing web page. The Ace git repository ships with a pre-packaged version of Ace inside of the `build` directory. The same packaged files are also available as a separate [download](https://github.com/ajaxorg/ace/downloads). Simply copy the contents of the `src` subdirectory somewhere into your project and take a look at the included demos of how to use Ace.
+
+The easiest version is simply:
+
+    <div id="editor">some text</div>
+    <script src="src/ace.js" type="text/javascript" charset="utf-8"></script>
+    <script>
+    document.onload = function() {
+        var editor = ace.edit("editor");
+    };
+    </script>
+    
+To change the theme simply include the Theme's JavaScript file
+
+    <script src="src/theme-twilight.js" type="text/javascript" charset="utf-8"></script>
+    
+and configure the editor to use the theme:
+
+    editor.setTheme("ace/theme/twilight");
+    
+By default the editor only supports plain text mode. However all other language modes are available as separate modules. After including the mode's Javascript file
+
+    <script src="src/mode-javascript.js" type="text/javascript" charset="utf-8"></script>
+    
+the mode can be used like this:
+
+    editor.getSession().setMode(new JavaScriptMode());
+
 Running Ace
 -----------
 
diff --git a/build/Readme.md b/build/Readme.md
index 8897212b..0841f109 100644
--- a/build/Readme.md
+++ b/build/Readme.md
@@ -35,6 +35,37 @@ Ace is a community project. We actively encourage and support contributions. The
     git clone git://github.com/ajaxorg/ace.git
     git submodule update --init --recursive
 
+Embedding Ace
+-------------
+
+Ace can be easily embedded into any existing web page. The Ace git repository ships with a pre-packaged version of Ace inside of the `build` directory. The same packaged files are also available as a separate [download](https://github.com/ajaxorg/ace/downloads). Simply copy the contents of the `src` subdirectory somewhere into your project and take a look at the included demos of how to use Ace.
+
+The easiest version is simply:
+
+    <div id="editor">some text</div>
+    <script src="src/ace.js" type="text/javascript" charset="utf-8"></script>
+    <script>
+    document.onload = function() {
+        var editor = ace.edit("editor");
+    };
+    </script>
+    
+To change the theme simply include the Theme's JavaScript file
+
+    <script src="src/theme-twilight.js" type="text/javascript" charset="utf-8"></script>
+    
+and configure the editor to use the theme:
+
+    editor.setTheme("ace/theme/twilight");
+    
+By default the editor only supports plain text mode. However all other language modes are available as separate modules. After including the mode's Javascript file
+
+    <script src="src/mode-javascript.js" type="text/javascript" charset="utf-8"></script>
+    
+the mode can be used like this:
+
+    editor.getSession().setMode(new JavaScriptMode());
+
 Running Ace
 -----------