allowing user to easily specify location of toc in document

- clarifying dynamic update feature as well

README.md

@@ -12,10 +12,12 @@ by github or other sites via a command line flag.
 - [Installation](#installation)
 - [Usage](#usage)
   - [Adding toc to all files in a directory and sub directories](#adding-toc-to-all-files-in-a-directory-and-sub-directories)
+  - [Update existing doctoc TOCs effortlessly](#update-existing-doctoc-tocs-effortlessly)
   - [Adding toc to a single file](#adding-toc-to-a-single-file)
     - [Example](#example)
   - [Using doctoc to generate links compatible with other sites](#using-doctoc-to-generate-links-compatible-with-other-sites)
     - [Example](#example-1)
+  - [Specifying location of toc](#specifying-location-of-toc)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -34,7 +36,11 @@ Go into the directory that contains you local git project and type:
 
 This will update all markdown files in the current directory and all its
 subdirectories with a table of content that will point at the anchors generated
-by the github markdown parser.
+by the markdown parser. Doctoc defaults to using the GitHub parser, but other [modes can be specified](#using-doctoc-to-generate-links-compatible-with-other-sites).
+
+### Update existing doctoc TOCs effortlessly
+
+If you already have a TOC inserted by doctoc, it will automatically be updated by running the command (rather than inserting a duplicate toc). Doctoc locates the TOC by the `<!-- START doctoc -->` and `<!-- END doctoc -->` comments, so you can also move a generated TOC to any other portion of your document and it will be updated there.
 
 ### Adding toc to a single file
 
@@ -53,13 +59,40 @@ In order to add a table of contents whose links are compatible other sites add t
 Available modes are:
 
 ```
---bitbucket	bitbucket.org
---nodejs	  nodejs.org
---github	  github.com
---gitlab	  gitlab.com
---ghost	    ghost.org
+--bitbucket bitbucket.org
+--nodejs    nodejs.org
+--github    github.com
+--gitlab    gitlab.com
+--ghost     ghost.org
 ```
 
 #### Example
 
     doctoc README.md --bitbucket
+
+### Specifying location of toc
+
+By default, doctoc places the toc at the top of the file. You can indicate to have it placed elsewhere with the following format:
+
+```
+<!-- START doctoc -->
+<!-- END doctoc -->
+```
+
+You place this code directly in your .md file. For example:
+
+```
+// my_new_post.md
+Here we are, introducing the post. It's going to be great!
+But first: a TOC for easy reference.
+
+<!-- START doctoc -->
+<!-- END doctoc -->
+
+# Section One
+
+Here we'll discuss...
+
+```
+
+Running doctoc will insert the toc to that location.

lib/transform.js

@@ -10,11 +10,11 @@ var start = '<!-- START doctoc generated TOC please keep comment here to allow a
   , end   = '<!-- END doctoc generated TOC please keep comment here to allow auto update -->'
 
 function matchesStart(line) {
-  return (/<!-- START doctoc generated TOC /).test(line);
+  return (/<!-- START doctoc /).test(line);
 }
 
 function matchesEnd(line) {
-  return (/<!-- END doctoc generated TOC /).test(line);
+  return (/<!-- END doctoc /).test(line);
 }
 
 function notNull(x) { return  x !== null; }