From e3b0406499b7c2735c147c0f377018997900f6ea Mon Sep 17 00:00:00 2001 From: Jayden Seric Date: Wed, 28 Feb 2018 13:26:14 +1100 Subject: [PATCH] Use reference links in Markdown. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixes https://github.com/documentationjs/documentation/issues/948. This approach might be problematic when inserting markdown under a readme heading if the readme already has link references with conflicting ID’s. --- docs/NODE_API.md | 96 ++++++++++++++++++++++++-------------- package.json | 1 + src/output/markdown_ast.js | 10 ++-- yarn.lock | 6 +++ 4 files changed, 73 insertions(+), 40 deletions(-) diff --git a/docs/NODE_API.md b/docs/NODE_API.md index d5d13c249..275a423fe 100644 --- a/docs/NODE_API.md +++ b/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,7 +148,7 @@ 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 @@ -156,7 +156,7 @@ 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/ diff --git a/package.json b/package.json index d5afc1ccc..984c1ce60 100644 --- a/package.json +++ b/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", diff --git a/src/output/markdown_ast.js b/src/output/markdown_ast.js index f479e6952..c60b208bc 100644 --- a/src/output/markdown_ast.js +++ b/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); } diff --git a/yarn.lock b/yarn.lock index a2f0d8ce2..f671a5dea 100644 --- a/yarn.lock +++ b/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"