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.

Specify the configuration file with the --config command-line option.

$ documentation build --config documentation.yml ...

Here's how documentation.yml works:

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. If you would like reuse your existing markdown files or just keep the content separate from the configuration you can use the file property. It is a filename it will be resolved against the directory that the documentation.yml file resides in.

So with a documentation.yml file like this

toc:
  - Map
  - name: Geography
    file: geo.md
  - LngLat
  - LngLatBounds

and a file geo.md

These are Mapbox GL JS's ways of representing locations
and areas on the sphere.

it would produce the same output as the previous example.

Groups

The children property can be used to group content under headings instead of just arranging them in order. Example:

toc:
  - name: Geography
    children:
      - Map
      - LngLat
      - LngLatBounds
  - name: Navigation
    description: |
      Here are some helper functions for navigation.
    children:
      - shortestPath
      - salesman