documentationjs · tmcw · Dec 7, 2015 · Nov 22, 2015 · Dec 7, 2015 · Dec 7, 2015
diff --git a/README.md b/README.md
@@ -50,7 +50,7 @@ lets you run `documentation` as a [Gulp](http://gulpjs.com/) build task.
 * [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
+* [Theming](docs/THEMING.md): tips for theming documentation output in HTML
 * [See also](docs/SEE_ALSO.md): a list of projects similar to documentation.js
 
 ## User Guide

diff --git a/docs/THEME_HTML.md b/docs/THEME_HTML.md
diff --git a/docs/THEMING.md b/docs/THEMING.md
@@ -1,27 +1,24 @@
-This assumes you have node.js installed:
+Documentation.js supports customizable themes for HTML output. A theme is a Node.js
+module that exports a single function with the following signature:
 
-First install dev-documentation:
-
-```
-npm install -g [email protected]
 ```
+/**
+ * @function
+ * @param {Array<Object>} comments - an array of comments to be output
+ * @param {Object} options - theme options
+ * @param {ThemeCallback} callback - see below
+ */
 
-Get a JSDoc-documented project to test against:
-
+/**
+ * @callback ThemeCallback
+ * @param {?Error} error
+ * @param {?Array<vinyl.File>} output
+ */
 ```
-git clone [email protected]:mapbox/mapbox-gl-js.git
-```
-
-Get a checkout of the default style
 
-```
-[email protected]:documentationjs/documentation-theme-default.git
-```
-
-Now start theming
-
-```
-dev-documentation mapbox-gl-js/js/mapbox-gl.js -t ./documentation-theme-default/
-```
+The theme function should call the callback with either an error, if one occurs,
+or an array of [vinyl](https://github.com/gulpjs/vinyl) `File` objects.
 
-If you have [LiveReload](https://chrome.google.com/webstore/detail/livereload/jnihajbhpnppcggbcgedagnkighmdlei) installed, you can enable it and it'll automatically refresh the page when you edit the theme.
+The theme is free to implement HTML generation however it chooses. See
+[the default theme](https://github.com/documentationjs/documentation-theme-default/)
+for some ideas.
diff --git a/lib/format_type.js b/lib/format_type.js
diff --git a/lib/get_template.js b/lib/get_template.js
diff --git a/lib/html_helpers.js b/lib/html_helpers.js