diff --git a/README.md b/README.md
index d891ddac6..ba8ca485b 100644
--- a/README.md
+++ b/README.md
@@ -33,6 +33,17 @@ sections of code it refers to in a GitHub repository.
 The [gulp-documentation](https://github.com/documentationjs/gulp-documentation) project
 lets you run `documentation` as a [Gulp](http://gulpjs.com/) build task.
 
+## Documentation
+
+* [Getting_Started](docs/GETTING_STARTED.md): start here
+* [Usage](docs/USAGE.md): how to use documentation.js
+* [Recipes](docs/RECIPES.md): tricks for writing effective JSDoc docs
+* [Node API](docs/NODE_API.md): documentation.js's self-generated documentation
+* [FAQ](docs/FAQ.md)
+
+* [Theming HTML](docs/THEME_HTML.md): tips for theming documentation output in HTML
+* [See also](docs/SEE_ALSO.md): a list of projects similar to documentation.js
+
 ## User Guide
 
 Globally install `documentation` using the [npm](https://www.npmjs.com/) package manager:
diff --git a/docs/NODE_API.md b/docs/NODE_API.md
new file mode 100644
index 000000000..85294fafe
--- /dev/null
+++ b/docs/NODE_API.md
@@ -0,0 +1,910 @@
+# autolink
+
+Link text to this page or to a central resource.
+
+
+**Parameters**
+
+-   `paths` **Array<string>** list of valid namespace paths that are linkable
+
+-   `text` **string** inner text of the link
+
+
+
+Returns **string** potentially linked HTML
+
+
+
+
+# commentsToAST
+
+Given a hierarchy-nested set of comments, generate an mdast-compatible
+Abstract Syntax Usable for generating Markdown output
+
+
+**Parameters**
+
+-   `comments` **Array<Object>** nested comment
+
+-   `opts` **Object** currently none accepted
+
+-   `callback` **Function** called with AST
+
+
+
+Returns **undefined** calls callback
+
+
+
+
+# countModuleIdentifiers
+
+Count leading identifiers that refer to a module export (`exports` or `module.exports`).
+
+
+**Parameters**
+
+-   `comment` **Object** parsed comment
+
+-   `identifiers` **Array<string>** array of identifier names
+
+
+
+Returns **number** number of identifiers referring to a module export (0, 1 or 2)
+
+
+
+
+# dependencyStream
+
+Returns a readable stream of dependencies, given an array of entry
+points and an object of options to provide to module-deps.
+
+This stream requires filesystem access, and thus isn't suitable
+for a browser environment.
+
+
+**Parameters**
+
+-   `indexes` **Array<string>** paths to entry files as strings
+
+-   `options` **Object** optional options passed
+
+-   `callback` **Function** called with (err, inputs)
+
+
+
+Returns **undefined** calls callback
+
+
+
+
+# documentation
+
+Generate JavaScript documentation as a list of parsed JSDoc
+comments, given a root file as a path.
+
+
+**Parameters**
+
+-   `indexes` **Array<string> or string** files to process
+
+-   `options` **Object** options
+    -   `options.external` **Array<string>** a string regex / glob match pattern
+        that defines what external modules will be whitelisted and included in the
+        generated documentation.
+
+    -   `options.transform` **Array<string>** source transforms given as strings
+        passed to [the module-deps transform option](https://github.com/substack/module-deps)
+
+    -   `options.polyglot` **[boolean]** parse comments with a regex rather than
+        a proper parser. This enables support of non-JavaScript languages but
+        reduces documentation's ability to infer structure of code.
+         (optional, default `false`)
+    -   `options.shallow` **[boolean]** whether to avoid dependency parsing
+        even in JavaScript code. With the polyglot option set, this has no effect.
+         (optional, default `false`)
+    -   `options.order` **[Array<string or Object>]** ] optional array that
+        defines sorting order of documentation
+         (optional, default `[`)
+-   `callback` **Function** to be called when the documentation generation
+    is complete, with (err, result) argumentsj
+
+
+
+Returns **undefined** calls callback
+
+
+
+
+# flatten
+
+Flattens tags in an opinionated way.
+
+The following tags are assumed to be singletons, and are flattened
+to a top-level property on the result whose value is extracted from
+the tag:
+
+-   `@name`
+-   `@memberof`
+-   `@classdesc`
+-   `@kind`
+-   `@class`
+-   `@constant`
+-   `@event`
+-   `@external`
+-   `@file`
+-   `@function`
+-   `@member`
+-   `@mixin`
+-   `@module`
+-   `@namespace`
+-   `@typedef`
+-   `@access`
+-   `@lends`
+
+The following tags are flattened to a top-level array-valued property:
+
+-   `@param` (to `params` property)
+-   `@property` (to `properties` property)
+-   `@returns` (to `returns` property)
+-   `@augments` (to `augments` property)
+-   `@example` (to `examples` property)
+-   `@throws` (to `throws` property)
+
+The `@global`, `@static`, `@instance`, and `@inner` tags are flattened
+to a `scope` property whose value is `"global"`, `"static"`, `"instance"`,
+or `"inner"`.
+
+The `@access`, `@public`, `@protected`, and `@private` tags are flattened
+to an `access` property whose value is `"protected"` or `"private"`.
+The assumed default value is `"public"`, so `@access public` or `@public`
+tags result in no `access` property.
+
+
+**Parameters**
+
+-   `comment` **Object** a parsed comment
+
+
+
+Returns **Object** comment with tags flattened
+
+
+
+
+# html
+
+Formats documentation as HTML.
+
+
+**Parameters**
+
+-   `comments` **Array<Object>** parsed comments
+
+-   `opts` **Object** Options that can customize the output
+    -   `opts.theme` **[string]** Name of a module used for an HTML theme.
+
+-   `callback` **Function** called with array of results as vinyl-fs objects
+
+
+
+Returns **undefined** calls callback
+
+
+
+
+# inferKind
+
+Infers a `kind` tag from other tags or from the context.
+
+
+**Parameters**
+
+-   `comment` **Object** parsed comment
+
+
+
+Returns **Object** comment with kind inferred
+
+
+
+
+# inferName
+
+Infers a `name` tag from the context,
+and adopt `@class` and other other tags as implied name tags.
+
+
+**Parameters**
+
+-   `comment` **Object** parsed comment
+
+
+
+Returns **Object** comment with name inferred
+
+
+
+
+# inferParams
+
+Infers param tags by reading function parameter names
+
+
+**Parameters**
+
+-   `comment` **Object** parsed comment
+
+
+
+Returns **Object** comment with parameters
+
+
+
+
+# inferReturn
+
+Infers returns tags by using Flow return type annotations
+
+
+**Parameters**
+
+-   `comment` **Object** parsed comment
+
+
+
+Returns **Object** comment with return tag inferred
+
+
+
+
+# isJSDocComment
+
+Detect whether a comment is a JSDoc comment: it must be a block
+comment which starts with two asterisks, not any other number of asterisks.
+
+The code parser automatically strips out the first asterisk that's
+required for the comment to be a comment at all, so we count the remaining
+comments.
+
+
+**Parameters**
+
+-   `comment` **Object** an ast-types node of the comment
+
+
+
+Returns **boolean** whether it is valid
+
+
+
+
+# json
+
+Formats documentation as a JSON string.
+
+
+**Parameters**
+
+-   `comments` **Array<Object>** parsed comments
+
+-   `opts` **Object** Options that can customize the output
+
+-   `callback` **Function** called with null, string
+
+
+
+Returns **undefined** calls callback
+
+
+
+
+# linkGitHub
+
+Attempts to link code to its place on GitHub.
+
+
+**Parameters**
+
+-   `comment` **Object** parsed comment
+
+
+
+Returns **Object** comment with github inferred
+
+
+
+
+# markdown
+
+Formats documentation as
+[Markdown](http://daringfireball.net/projects/markdown/).
+
+
+**Parameters**
+
+-   `comments` **Array<Object>** parsed comments
+
+-   `opts` **Object** Options that can customize the output
+
+-   `callback` **Function** called with null, string
+
+
+
+Returns **undefined** calls callback
+
+
+
+
+# nestParams
+
+Nests
+[parameters with properties](http://usejsdoc.org/tags-param.html#parameters-with-properties).
+
+A parameter `employee.name` will be attached to the parent parameter `employee` in
+a `properties` array.
+
+This assumes that incoming comments have been flattened.
+
+
+**Parameters**
+
+-   `comment` **Object** input comment
+
+
+
+Returns **Object** nested comment
+
+
+
+
+# normalize
+
+Normalizes synonymous tags to the canonical tag type listed on <http://usejsdoc.org/>.
+
+For example, given the input object:
+
+    { tags: [
+      { title: "virtual" },
+      { title: "return", ... }
+    ]}
+
+The output object will be:
+
+    { tags: [
+      { title: "abstract" },
+      { title: "returns", ... }
+    ]}
+
+The following synonyms are normalized:
+
+-   virtual -> abstract
+-   extends -> augments
+-   constructor -> class
+-   const -> constant
+-   defaultvalue -> default
+-   desc -> description
+-   host -> external
+-   fileoverview, overview -> file
+-   emits -> fires
+-   func, method -> function
+-   var -> member
+-   arg, argument -> param
+-   prop -> property
+-   return -> returns
+-   exception -> throws
+-   linkcode, linkplain -> link
+
+
+**Parameters**
+
+-   `comment` **Object** parsed comment
+
+
+
+Returns **Object** comment with normalized properties
+
+
+
+
+# externals
+
+Create a filter function for use with module-deps, allowing the specified
+external modules through.
+
+
+**Parameters**
+
+-   `indexes` **Array&lt;string&gt;** the list of entry points that will be
+    used by module-deps
+
+-   `options` **Object** An options object with `external` being a
+    micromatch-compaitible glob. _NOTE:_ the glob will be matched relative to
+    the top-level node_modules directory for each entry point.
+
+
+
+Returns **function** A function for use as the module-deps `postFilter`
+options.
+
+
+
+
+# filterAccess
+
+Exclude given access levels from the generated documentation: this allows
+users to write documentation for non-public members by using the
+`@private` tag.
+
+
+**Parameters**
+
+-   `levels` **[Array&lt;string&gt;]** ] excluded access levels.
+     (optional, default `['private'`)
+-   `comments` **Array&lt;Object&gt;** parsed comments (can be nested)
+
+
+
+Returns **Array&lt;Object&gt;** filtered comments
+
+
+
+
+# filterJS
+
+Node & browserify support requiring JSON files. JSON files can't be documented
+with JSDoc or parsed with espree, so we filter them out before
+they reach documentation's machinery.
+
+
+**Parameters**
+
+-   `data` **Object** a file as an object with 'file' property
+
+
+
+Returns **boolean** whether the file is json
+
+
+
+
+# findGit
+
+Given a full path to a single file, iterate upwards through the filesystem
+to find a directory with a .git file indicating that it is a git repository
+
+
+**Parameters**
+
+-   `filename` **string** any file within a repository
+
+
+
+Returns **string** repository path
+
+
+
+
+# formatMarkdown
+
+This helper is exposed in templates as `md` and is useful for showing
+Markdown-formatted text as proper HTML.
+
+
+**Parameters**
+
+-   `string` **string** 
+
+
+
+**Examples**
+
+```javascript
+var x = '## foo';
+// in template
+// {{ md x }}
+// generates <h2>foo</h2>
+```
+
+
+
+Returns **string** string
+
+
+
+
+# formatParameter
+
+Format a parameter name. This is used in formatParameters
+and just needs to be careful about differentiating optional
+parameters
+
+
+**Parameters**
+
+-   `param` **Object** a param as a type spec
+
+
+
+Returns **string** formatted parameter representation.
+
+
+
+
+# formatParameters
+
+Format the parameters of a function into a quickly-readable
+summary that resembles how you would call the function
+initially.
+
+
+Returns **string** formatted parameters
+
+
+
+
+# formatType
+
+Helper used to format JSDoc-style type definitions into HTML.
+
+
+**Parameters**
+
+-   `type` **Object** type object in doctrine style
+
+-   `paths` **Array&lt;string&gt;** valid namespace paths that can be linked
+
+
+
+**Examples**
+
+```javascript
+var x = { type: 'NameExpression', name: 'String' };
+// in template
+// {{ type x }}
+// generates String
+```
+
+
+
+Returns **string** string
+
+
+
+
+# generate
+
+Generate an AST chunk for a comment at a given depth: this is
+split from the main function to handle hierarchially nested comments
+
+
+**Parameters**
+
+-   `depth` **number** nesting of the comment, starting at 1
+
+-   `comment` **Object** a single comment
+
+
+
+Returns **Object** mdast-compatible AST
+
+
+
+
+# getGithubURLPrefix
+
+Given a a root directory, find its git configuration and figure out
+the HTTPS URL at the base of that GitHub repository.
+
+
+**Parameters**
+
+-   `root` **string** path at the base of this local repo
+
+
+
+Returns **string** base HTTPS url of the GitHub repository
+
+
+
+
+# getTemplate
+
+Get a Handlebars template file out of a theme and compile it into
+a template function
+
+
+**Parameters**
+
+-   `Handlebars` **Object** handlebars instance
+
+-   `themeModule` **string** base directory of themey
+
+-   `name` **string** template name
+
+
+
+Returns **Function** template function
+
+
+
+
+# hierarchy
+
+
+
+
+**Parameters**
+
+-   `comments` **Array&lt;Object&gt;** an array of parsed comments
+
+
+
+Returns **Array&lt;Object&gt;** nested comments, with only root comments
+at the top level.
+
+
+
+
+# highlight
+
+Highlights the contents of the `example` tag.
+
+
+**Parameters**
+
+-   `comment` **Object** parsed comment
+
+
+
+Returns **Object** comment with highlighted code
+
+
+
+
+# highlightString
+
+Given a string of JavaScript, return a string of HTML representing
+that JavaScript highlighted.
+
+
+**Parameters**
+
+-   `example` **string** string of javascript
+
+
+
+Returns **string** highlighted html
+
+
+
+
+# htmlHelpers
+
+Given a Handlebars instance, register helpers
+
+
+**Parameters**
+
+-   `Handlebars` **Object** template instance
+
+-   `paths` **Array&lt;string&gt;** list of valid namespace paths that are linkable
+
+
+
+Returns **undefined** invokes side effects on Handlebars
+
+
+
+
+# lint
+
+Passively lints and checks documentation data.
+
+
+**Parameters**
+
+-   `comment` **Object** parsed comment
+
+
+
+Returns **Array&lt;Object&gt;** array of errors
+
+
+
+
+# markdownLink
+
+Format a description and target as a Markdown link.
+
+
+**Parameters**
+
+-   `description` **string** the text seen as the link
+
+-   `href` **string** where the link goes
+
+
+
+Returns **string** markdown formatted link
+
+
+
+
+# membership
+
+Uses code structure to infer `memberof`, `instance`, and `static`
+tags from the placement of JSDoc
+annotations within a file
+
+
+**Parameters**
+
+-   `comment` **Object** parsed comment
+
+
+
+Returns **Object** comment with membership inferred
+
+
+
+
+# paramWithDefaultToDoc
+
+Given a parameter like
+
+    function a(b = 1)
+
+Format it as an optional parameter in JSDoc land
+
+
+**Parameters**
+
+-   `param` **Object** ESTree node
+
+
+
+Returns **Object** JSDoc param
+
+
+
+
+# parseComment
+
+Parse a comment with doctrine and decorate the result with file position and code context.
+
+
+**Parameters**
+
+-   `comment` **Object** the current state of the parsed JSDoc comment
+
+
+
+Returns **undefined** this emits data
+
+
+
+
+# parseJSDoc
+
+Parse a comment with doctrine, decorate the result with file position and code
+context, handle parsing errors, and fix up various infelicities in the structure
+outputted by doctrine.
+
+
+**Parameters**
+
+-   `comment` **string** input to be parsed
+
+-   `loc` **Object** location of the input
+
+-   `context` **Object** code context of the input
+
+
+
+Returns **Object** an object conforming to the
+[documentation JSON API](https://github.com/documentationjs/api-json) schema
+
+
+
+
+# parseJavaScript
+
+Receives a module-dep item,
+reads the file, parses the JavaScript, and parses the JSDoc.
+
+
+**Parameters**
+
+-   `data` **Object** a chunk of data provided by module-deps
+
+
+
+Returns **Array&lt;Object&gt;** an array of parsed comments
+
+
+
+
+# parsePolyglot
+
+Documentation stream parser: this receives a module-dep item,
+reads the file, parses the JavaScript, parses the JSDoc, and
+emits parsed comments.
+
+
+**Parameters**
+
+-   `data` **Object** a chunk of data provided by module-deps
+
+
+
+Returns **Array&lt;Object&gt;** adds to memo
+
+
+
+
+# resolveTheme
+
+Given the name of a theme as a module, return the directory it
+resides in, or throw an error if it is not found
+
+
+**Parameters**
+
+-   `theme` **string** the module name
+
+
+
+Returns **string** directory
+
+
+
+
+# shallow
+
+A readable source for content that doesn't do dependency resolution, but
+simply reads files and pushes them onto a stream.
+
+If an array of strings is provided as input to this method, then
+they will be treated as filenames and read into the stream.
+
+If an array of objects is provided, then we assume that they are valid
+objects with `source` and `file` properties, and don't use the filesystem
+at all. This is one way of getting documentation.js to run in a browser
+or without fs access.
+
+
+**Parameters**
+
+-   `indexes` **Array&lt;string or Object&gt;** entry points
+
+-   `options` **Object** parsing options
+
+-   `callback` **Function** called with (err, inputs)
+
+
+
+Returns **undefined** calls callback
+
+
+
+
+# walk
+
+Apply a function to all comments within a hierarchy: this iterates
+through children in the 'members' property.
+
+
+**Parameters**
+
+-   `comments` **Array&lt;Object&gt;** an array of nested comments
+
+-   `fn` **Function** a walker function
+
+
+
+Returns **Array&lt;Object&gt;** comments
+
+
+