Merge pull request #337 from documentationjs/wooorm-rename-mdast-remark

Rename mdast to remark

Author: tmcw

docs/NODE_API.md

@@ -18,7 +18,7 @@ Returns **string** potentially linked HTML
 
 # commentsToAST
 
-Given a hierarchy-nested set of comments, generate an mdast-compatible
+Given a hierarchy-nested set of comments, generate an remark-compatible
 Abstract Syntax Usable for generating Markdown output
 
 
@@ -583,7 +583,7 @@ split from the main function to handle hierarchially nested comments
 
 
 
-Returns **Object** mdast-compatible AST
+Returns **Object** remark-compatible AST
 
 
 

index.js

@@ -183,6 +183,6 @@ module.exports.expandInputs = expandInputs;
 module.exports.formats = {
   html: require('./lib/output/html'),
   md: require('./lib/output/markdown'),
-  mdast: require('./lib/output/markdown_ast'),
+  remark: require('./lib/output/markdown_ast'),
   json: require('./lib/output/json')
 };

lib/commands/readme.js

@@ -1,7 +1,7 @@
 'use strict';
 
 var fs = require('fs');
-var mdast = require('mdast');
+var remark = require('remark');
 var inject = require('mdast-util-inject');
 var chalk = require('chalk');
 var disparity = require('disparity');
@@ -38,7 +38,7 @@ module.exports.parseArgs = function (yargs) {
 
 function readme(documentation, parsedArgs) {
   var readmeOptions = parsedArgs.commandOptions;
-  readmeOptions.format = 'mdast';
+  readmeOptions.format = 'remark';
   /* eslint no-console: 0 */
   var log = readmeOptions.q ? function () {}
   : console.log.bind(console, '[documentation-readme] ');
@@ -51,7 +51,7 @@ function readme(documentation, parsedArgs) {
       throw err;
     }
     var readmeContent = fs.readFileSync(readmeFile, 'utf8');
-    mdast.use(plugin, {
+    remark.use(plugin, {
       section: readmeOptions.section,
       toInject: docsAst
     }).process(readmeContent, onInjected.bind(null, readmeContent));
@@ -81,8 +81,8 @@ function readme(documentation, parsedArgs) {
   }
 }
 
-// wrap the inject utility as an mdast plugin
-function plugin(mdast, options) {
+// wrap the inject utility as an remark plugin
+function plugin(remark, options) {
   return function transform(targetAst, file, next) {
     if (!inject(options.section, targetAst, options.toInject)) {
       return next(new Error('Heading ' + options.section + ' not found.'));

lib/output/html.js

@@ -1,42 +1,6 @@
 'use strict';
 
-var walk = require('../walk'),
-  path = require('path'),
-  hljs = require('highlight.js');
-
-/**
- * Create a highlighter function that transforms strings of code
- * into strings of HTML with highlighting tags.
- *
- * @param {boolean} auto whether to automatically detect a language
- * @returns {Function} highlighter function
- */
-function highlightString(auto) {
-  return function (example) {
-    if (auto) {
-      return hljs.highlightAuto(example || '').value;
-    }
-    return hljs.highlight('js', example || '').value;
-  };
-}
-
-/**
- * Highlights the contents of the `example` tag.
- * @name highlight
- * @param {Object} comment parsed comment
- * @param {Object} [options] options
- * @return {Object} comment with highlighted code
- */
-function highlight(comment, options) {
-  var hljsOptions = options.hljs || {};
-  hljs.configure(hljsOptions);
-
-  if (comment.examples) {
-    comment.examples = comment.examples.map(highlightString(hljsOptions.highlightAuto));
-  }
-
-  return comment;
-}
+var path = require('path');
 
 /**
  * Formats documentation as HTML.
@@ -50,7 +14,6 @@ function highlight(comment, options) {
  */
 module.exports = function makeHTML(comments, options, callback) {
   options = options || {};
-  comments = walk(comments, highlight, options);
   var theme = require('documentation-theme-default');
   if (options.theme) {
     theme = require(path.resolve(process.cwd(), options.theme));

lib/output/markdown.js

@@ -1,7 +1,7 @@
 'use strict';
 
-var mdast = require('mdast'),
-  toc = require('mdast-toc'),
+var remark = require('remark'),
+  toc = require('remark-toc'),
   markdownAST = require('./markdown_ast');
 
 /**
@@ -15,7 +15,7 @@ var mdast = require('mdast'),
  * @return {undefined} calls callback
  */
 module.exports = function (comments, opts, callback) {
-  var processor = mdast().use(toc);
+  var processor = remark().use(toc);
   markdownAST(comments, opts, function (err, ast) {
     var processedAST = processor.run(ast);
     return callback(null, processor.stringify(processedAST));

lib/output/markdown_ast.js

@@ -1,11 +1,11 @@
-var mdast = require('mdast'),
+var remark = require('remark'),
   u = require('unist-builder'),
   formatType = require('documentation-theme-utils').formatType,
   formatInlineTags = require('../format_inline_tags'),
   hljs = require('highlight.js');
 
 /**
- * Given a hierarchy-nested set of comments, generate an mdast-compatible
+ * Given a hierarchy-nested set of comments, generate an remark-compatible
  * Abstract Syntax Tree usable for generating Markdown output
  *
  * @param {Array<Object>} comments nested comment
@@ -25,7 +25,7 @@ function commentsToAST(comments, opts, callback) {
    *
    * @param {number} depth nesting of the comment, starting at 1
    * @param {Object} comment a single comment
-   * @returns {Object} mdast-compatible AST
+   * @returns {Object} remark-compatible AST
    */
   function generate(depth, comment) {
 
@@ -37,7 +37,7 @@ function commentsToAST(comments, opts, callback) {
             u('text', ' '),
             !!param.type && u('strong', formatType(param.type)),
             u('text', ' ')
-          ].concat(mdast.parse(formatInlineTags(param.description)).children)
+          ].concat(remark.parse(formatInlineTags(param.description)).children)
           .concat([
             !!param.default && u('paragraph', [
               u('text', ' (optional, default '),
@@ -74,7 +74,7 @@ function commentsToAST(comments, opts, callback) {
               u('strong', formatType(property.type)),
               u('text', ' ')
             ]
-            .concat(mdast.parse(formatInlineTags(property.description)).children)
+            .concat(remark.parse(formatInlineTags(property.description)).children)
             .filter(Boolean)),
             property.properties && propertyList(property.properties)
           ].filter(Boolean));
@@ -95,7 +95,7 @@ function commentsToAST(comments, opts, callback) {
           u('text', 'Returns '),
           u('strong', formatType(returns.type)),
           u('text', ' ')
-        ].concat(mdast.parse(formatInlineTags(returns.description)).children));
+        ].concat(remark.parse(formatInlineTags(returns.description)).children));
       });
     }
 
@@ -141,10 +141,10 @@ function commentsToAST(comments, opts, callback) {
           })));
     }
 
-    return [u('heading', { depth: depth }, [u('text', comment.name)])]
+    return [u('heading', { depth: depth }, [u('text', comment.name || '')])]
     .concat(githubLink(comment))
     .concat(augmentsLink(comment))
-    .concat(mdast.parse(formatInlineTags(comment.description)).children)
+    .concat(remark.parse(formatInlineTags(comment.description)).children)
     .concat(paramSection(comment))
     .concat(propertySection(comment))
     .concat(examplesSection(comment))

package.json

@@ -17,22 +17,22 @@
     "debounce": "^1.0.0",
     "disparity": "^2.0.0",
     "doctrine": "^0.7.1",
-    "documentation-theme-default": "2.2.1",
-    "documentation-theme-utils": "^1.0.1",
+    "documentation-theme-default": "2.2.3",
+    "documentation-theme-utils": "^1.2.1",
     "events": "^1.1.0",
     "extend": "^3.0.0",
     "get-comments": "^1.0.1",
     "github-url-from-git": "^1.4.0",
-    "highlight.js": "^8.4.0",
+    "highlight.js": "^9.1.0",
     "js-yaml": "^3.3.1",
     "jsdoc-inline-lex": "^1.0.1",
-    "mdast": "^2.0.0",
-    "mdast-toc": "^1.1.0",
     "mdast-util-inject": "^1.1.0",
     "micromatch": "^2.1.6",
     "mime": "^1.3.4",
     "module-deps": "^4.0.2",
     "parse-filepath": "^0.6.3",
+    "remark": "^3.0.0",
+    "remark-toc": "^2.0.0",
     "remote-origin-url": "^0.4.0",
     "resolve": "^1.1.6",
     "slugg": "^0.1.2",

test/bin.js

@@ -259,9 +259,9 @@ test('write to html, highlightAuto', function (t) {
       var result = fs.readFileSync(path.join(dstDir, 'index.html'), 'utf8');
       t.ok(result.indexOf('<span class="hljs-number">42</span>') > 0,
         'javascript is recognized by highlightjs');
-      t.ok(result.indexOf('<span class="hljs-attr_selector">[data-foo]</span>') > 0,
+      t.ok(result.indexOf('<span class="hljs-selector-attr">[data-foo]</span>') > 0,
         'css is recognized by highlightjs');
-      t.ok(result.indexOf('<span class="hljs-attribute">data-foo</span>') > 0,
+      t.ok(result.indexOf('<span class="hljs-attr">data-foo</span>') > 0,
         'html is recognized by highlightjs');
       t.end();
     }, false);

test/fixture/empty-example.output.json

@@ -32,7 +32,9 @@
       "code": "/**\n * This function returns the number plus two.\n *\n * @example\n */\nfunction returnTwo() {\n  return a + 2;\n}\n"
     },
     "errors": [],
-    "examples": [null],
+    "examples": [
+      null
+    ],
     "name": "returnTwo",
     "kind": "function",
     "members": {
@@ -43,4 +45,4 @@
       "returnTwo"
     ]
   }
-]
+]

test/fixture/empty-example.output.md.json

@@ -51,9 +51,9 @@
         }
       ]
     },
-    {                                           
-         "lang": "javascript",
-         "type": "code"
+    {
+      "lang": "javascript",
+      "type": "code"
     }
   ]
-}
+}