feat(config): add file property for notes

Fixes documentationjs#609

Author: dignifiedquire

docs/CONFIG.md

@@ -27,3 +27,24 @@ This puts the top level API documentation for the `Map`, `LngLat`, and `LngLatBo
 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 that will be resolved against `process.cwd()`.
+
+So with a `documentation.yml` file like this
+
+```yml
+toc:
+  - Map
+  - name: Geography
+    file: geo.md
+  - LngLat
+  - LngLatBounds
+```
+
+and a file `geo.md`
+
+```markdown
+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.

lib/sort.js

@@ -2,6 +2,8 @@
 
 var parseMarkdown = require('./parse_markdown');
 var chalk = require('chalk');
+var path = require('path');
+var fs = require('fs');
 
 /**
  * Sort two documentation objects, given an optional order object. Returns
@@ -36,6 +38,15 @@ module.exports = function sortDocs(comments, options) {
   var fixed = options.toc.filter(function (val) {
     return typeof val === 'object' && val.name;
   }).map(function (val) {
+    if (typeof val.file === 'string') {
+      var filename = path.join(process.cwd(), val.file);
+      try {
+        val.description = fs.readFileSync(filename).toString();
+        delete val.file;
+      } catch (err) {
+        process.stderr.write(chalk.red('Failed to read file ' + filename));
+      }
+    }
     if (typeof val.description === 'string') {
       val.description = parseMarkdown(val.description);
     }

test/fixture/snowflake.md

@@ -0,0 +1 @@
+# The Snowflake

test/lib/sort.js

@@ -177,3 +177,53 @@ test('sort an already-sorted stream containing a section/description', function
   t.deepEqual(sortTwice, [carrot, sectionMarkdown, bananas, apples]);
   t.end();
 });
+
+test('sort toc with files', function (t) {
+  var apples = { context: { sortKey: 'a' }, name: 'apples' };
+  var carrot = { context: { sortKey: 'b' }, name: 'carrot' };
+  var bananas = { context: { sortKey: 'c' }, name: 'bananas' };
+
+  var snowflake = {
+    name: 'snowflake',
+    file: 'test/fixture/snowflake.md'
+  };
+
+  var processedSnowflake = {
+    name: 'snowflake',
+    kind: 'note',
+    description: {
+      children: [{
+        children: [{
+          position: {
+            end: {column: 16, line: 1, offset: 15},
+            indent: [],
+            start: {column: 3, line: 1, offset: 2}
+          },
+          type: 'text',
+          value: 'The Snowflake'
+        }],
+        depth: 1,
+        position: {
+          end: {column: 16, line: 1, offset: 15},
+          indent: [],
+          start: {column: 1, line: 1, offset: 0}
+        },
+        type: 'heading'
+      }],
+      position: {
+        end: {column: 1, line: 2, offset: 16},
+        start: {column: 1, line: 1, offset: 0}
+      },
+      type: 'root'
+    }
+  };
+  t.deepEqual(sort([
+    apples, carrot, bananas
+  ], {
+    toc: [snowflake]
+  }), [
+    processedSnowflake, apples, carrot, bananas
+  ], 'with configuration');
+
+  t.end();
+});