Use reference links in Markdown.

Fixes documentationjs#948.

This approach might be problematic when inserting markdown under a readme heading if the readme already has link references with conflicting ID’s.

Author: jaydenseric

docs/NODE_API.md

@@ -2,12 +2,12 @@
 
 ### Table of Contents
 
--   [lint](#lint)
--   [build](#build)
--   [formats](#formats)
--   [formats.html](#formatshtml)
--   [formats.markdown](#formatsmarkdown)
--   [formats.json](#formatsjson)
+-   [lint][1]
+-   [build][2]
+-   [formats][3]
+-   [formats.html][4]
+-   [formats.markdown][5]
+-   [formats.json][6]
 
 ## lint
 
@@ -17,18 +17,18 @@ of lint information intended for human-readable output.
 
 **Parameters**
 
--   `indexes` **([Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)> | [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))** files to process
--   `args` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** args
-    -   `args.external` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>** a string regex / glob match pattern
+-   `indexes` **([Array][7]<[string][8]> | [string][8])** files to process
+-   `args` **[Object][9]** args
+    -   `args.external` **[Array][7]<[string][8]>** a string regex / glob match pattern
         that defines what external modules will be whitelisted and included in the
         generated documentation.
-    -   `args.shallow` **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** whether to avoid dependency parsing
+    -   `args.shallow` **[boolean][10]** whether to avoid dependency parsing
         even in JavaScript code. (optional, default `false`)
-    -   `args.inferPrivate` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** a valid regular expression string
+    -   `args.inferPrivate` **[string][8]?** a valid regular expression string
         to infer whether a code element should be private, given its naming structure.
         For instance, you can specify `inferPrivate: '^_'` to automatically treat
         methods named like `_myMethod` as private.
-    -   `args.extension` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>)?** treat additional file extensions
+    -   `args.extension` **([string][8] \| [Array][7]<[string][8]>)?** treat additional file extensions
         as JavaScript, extending the default set of `js`, `es6`, and `jsx`.
 
 **Examples**
@@ -44,7 +44,7 @@ documentation.lint('file.js').then(lintOutput => {
 });
 ```
 
-Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)** promise with lint results
+Returns **[Promise][11]** promise with lint results
 
 ## build
 
@@ -53,25 +53,25 @@ comments, given a root file as a path.
 
 **Parameters**
 
--   `indexes` **([Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)> | [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))** files to process
--   `args` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** args
-    -   `args.external` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>** a string regex / glob match pattern
+-   `indexes` **([Array][7]<[string][8]> | [string][8])** files to process
+-   `args` **[Object][9]** args
+    -   `args.external` **[Array][7]<[string][8]>** a string regex / glob match pattern
         that defines what external modules will be whitelisted and included in the
         generated documentation.
-    -   `args.shallow` **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** whether to avoid dependency parsing
+    -   `args.shallow` **[boolean][10]** whether to avoid dependency parsing
         even in JavaScript code. (optional, default `false`)
-    -   `args.order` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object))>** optional array that
+    -   `args.order` **[Array][7]<([string][8] \| [Object][9])>** optional array that
         defines sorting order of documentation (optional, default `[]`)
-    -   `args.access` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>** an array of access levels
+    -   `args.access` **[Array][7]<[string][8]>** an array of access levels
         to output in documentation (optional, default `[]`)
-    -   `args.hljs` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** hljs optional args
-        -   `args.hljs.highlightAuto` **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** hljs automatically detect language (optional, default `false`)
-        -   `args.hljs.languages` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)?** languages for hljs to choose from
-    -   `args.inferPrivate` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** a valid regular expression string
+    -   `args.hljs` **[Object][9]?** hljs optional args
+        -   `args.hljs.highlightAuto` **[boolean][10]** hljs automatically detect language (optional, default `false`)
+        -   `args.hljs.languages` **[Array][7]?** languages for hljs to choose from
+    -   `args.inferPrivate` **[string][8]?** a valid regular expression string
         to infer whether a code element should be private, given its naming structure.
         For instance, you can specify `inferPrivate: '^_'` to automatically treat
         methods named like `_myMethod` as private.
-    -   `args.extension` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>)?** treat additional file extensions
+    -   `args.extension` **([string][8] \| [Array][7]<[string][8]>)?** treat additional file extensions
         as JavaScript, extending the default set of `js`, `es6`, and `jsx`.
 
 **Examples**
@@ -89,7 +89,7 @@ documentation.build(['index.js'], {
 });
 ```
 
-Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)** results
+Returns **[Promise][11]** results
 
 ## formats
 
@@ -104,9 +104,9 @@ Formats documentation as HTML.
 
 **Parameters**
 
--   `comments` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[Comment](https://developer.mozilla.org/docs/Web/API/Comment/Comment)>** parsed comments
--   `config` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Options that can customize the output
-    -   `config.theme` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Name of a module used for an HTML theme. (optional, default `'default_theme'`)
+-   `comments` **[Array][7]<[Comment][12]>** parsed comments
+-   `config` **[Object][9]** Options that can customize the output
+    -   `config.theme` **[string][8]** Name of a module used for an HTML theme. (optional, default `'default_theme'`)
 
 **Examples**
 
@@ -122,17 +122,17 @@ documentation.build(['index.js'])
   });
 ```
 
-Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)>>** Promise with results
+Returns **[Promise][11]<[Array][7]<[Object][9]>>** Promise with results
 
 ## formats.markdown
 
 Formats documentation as
-[Markdown](http://daringfireball.net/projects/markdown/).
+[Markdown][13].
 
 **Parameters**
 
--   `comments` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)>** parsed comments
--   `args` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Options that can customize the output
+-   `comments` **[Array][7]<[Object][9]>** parsed comments
+-   `args` **[Object][9]** Options that can customize the output
 
 **Examples**
 
@@ -148,15 +148,15 @@ documentation.build(['index.js'])
   });
 ```
 
-Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>** a promise of the eventual value
+Returns **[Promise][11]<[string][8]>** a promise of the eventual value
 
 ## formats.json
 
 Formats documentation as a JSON string.
 
 **Parameters**
 
--   `comments` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[Comment](https://developer.mozilla.org/docs/Web/API/Comment/Comment)>** parsed comments
+-   `comments` **[Array][7]<[Comment][12]>** parsed comments
 
 **Examples**
 
@@ -172,4 +172,30 @@ documentation.build(['index.js'])
   });
 ```
 
-Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>** 
+Returns **[Promise][11]<[string][8]>** 
+
+[1]: #lint
+
+[2]: #build
+
+[3]: #formats
+
+[4]: #formatshtml
+
+[5]: #formatsmarkdown
+
+[6]: #formatsjson
+
+[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
+
+[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+
+[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+
+[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
+
+[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise
+
+[12]: https://developer.mozilla.org/docs/Web/API/Comment/Comment
+
+[13]: http://daringfireball.net/projects/markdown/

package.json

@@ -41,6 +41,7 @@
     "read-pkg-up": "^3.0.0",
     "remark": "^9.0.0",
     "remark-html": "7.0.0",
+    "remark-reference-links": "^4.0.1",
     "remark-toc": "^5.0.0",
     "remote-origin-url": "0.4.0",
     "shelljs": "^0.8.1",

src/output/markdown_ast.js

@@ -4,6 +4,7 @@ const u = require('unist-builder');
 const remark = require('remark');
 const mergeConfig = require('../merge_config');
 const toc = require('remark-toc');
+const links = require('remark-reference-links');
 const hljs = require('highlight.js');
 const GithubSlugger = require('github-slugger');
 const LinkerStack = require('./util/linker_stack');
@@ -374,11 +375,10 @@ function buildMarkdownAST(
     )
   );
 
-  if (config.markdownToc) {
-    root = remark()
-      .use(toc, { tight: true })
-      .run(root);
-  }
+  const pluginRemark = remark();
+  if (config.markdownToc) pluginRemark.use(toc, { tight: true });
+  pluginRemark.use(links);
+  root = pluginRemark.run(root);
 
   return Promise.resolve(root);
 }

yarn.lock

@@ -5030,6 +5030,12 @@ remark-parse@^5.0.0:
     vfile-location "^2.0.0"
     xtend "^4.0.1"
 
+remark-reference-links@^4.0.1:
+  version "4.0.1"
+  resolved "https://registry.yarnpkg.com/remark-reference-links/-/remark-reference-links-4.0.1.tgz#021aed1c55c187d712b3c76d0057bf510d300ba7"
+  dependencies:
+    unist-util-visit "^1.0.0"
+
 remark-slug@^5.0.0:
   version "5.0.0"
   resolved "https://registry.yarnpkg.com/remark-slug/-/remark-slug-5.0.0.tgz#9de71fcdc2bfae33ebb4a41eb83035288a829980"