README.md in sablon-0.0.19.beta4 vs README.md in sablon-0.0.19.beta5

@@ -98,12 +98,17 @@
 
 IMPORTANT: This feature is very much *experimental*. Currently, the insertion
     will replace the containing paragraph. This means that other content in the same
     paragraph is discarded.
 
-##### Markdown [experimental]
+##### Markdown [deprecated]
 
+IMPORTANT: Markdown insertion has been deprecated in favor of HTML
+    insertion. For now the behavior is still packaged with sablon. Note that the
+    implementation of `Sablon::Content::Markdown` is already based on
+    `Sablon::Content::HTML`. Markdown insertion will be removed in the future.
+
 Similar to WordProcessingML it's possible to use markdown while processing the
 tempalte. You don't need to modify your templates, a simple insertion operation
 is sufficient:
 
 ```
@@ -156,11 +161,11 @@
 To use HTML insertion prepare the context like so:
 
 ```ruby
 html_body = <<-HTML
 <div>This text can contain <em>additional formatting</em>
-according to the <strong>Markdown</strongstrong> specification.</div>
+according to the <strong>HTML</strong> specification.</div>
 HTML
 context = {
   article: { html_body: Sablon.content(:html, html_body) }
 }
 template.render_to_file File.expand_path("~/Desktop/output.docx"), context
@@ -216,9 +221,20 @@
 
 #### Nesting
 
 It is possible to nest loops and conditionals.
 
+#### Comments
+
+Sometimes it's necessary to include markup in the template that should not be
+visible in the rendered output. For example when defining sample numbering
+styles for HTML insertion.
+
+```
+«comment»
+    ... arbitrary document markup ...
+«endComment»
+```
 
 ### Executable
 
 The `sablon` executable can be used to process templates on the command-line.
 The usage is as follows: