Document sorting/configuration system. Fixes #100. Fixes #14

Author: tmcw

docs/CONFIG.md

@@ -0,0 +1,29 @@
+# Configuring documentation.js
+
+Configuration is a completely optional step for generating documentation
+with documentation.js. The tool is designed to accept any JSDoc-annotated
+source code and automatically generate output.
+
+Configuration - a `documentation.yml` file - will accomplish two goals:
+
+* Organization: you can put top level documentation in order of importance
+* Narration: you can add narrative sections - plain English writing - in
+  between autogenerated API documentation.
+
+Here's how `documentation.yml` works:
+
+```yml
+toc:
+  - Map
+  - name: Geography
+    description: |
+      These are Mapbox GL JS's ways of representing locations
+      and areas on the sphere.
+  - LngLat
+  - LngLatBounds
+```
+
+This puts the top level API documentation for the `Map`, `LngLat`, and `LngLatBounds`
+items in the given order, and inserts a narrative item titled `Geography`
+after the section on maps. The `description` property of that narrative item
+is interpreted as Markdown.