documentation/docs/CONFIG.md

# 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.