Add support for enforcing documents with document: true

Related to 475366c.
Related to GH-27.

Closes remarkjs/remark#273.

Author: wooorm

README.md

@@ -43,6 +43,12 @@ Transform the given [HAST][] tree to an [MDAST][] tree.
 Object mapping tag-names to functions handling those elements.
 Take a look at [`handlers/`][handlers] for examples.
 
+###### `options.document`
+
+Whether the given tree is a complete document.  If `document: true`,
+implicit paragraphs are added in the `root` node around inline MDAST nodes.
+Otherwise, inline MDAST nodes are wrapped when needed.
+
 ## Related
 
 *   [`mdast-util-to-hast`][mdast-util-to-hast]

handlers/root.js

@@ -6,5 +6,11 @@ var all = require('../all');
 var wrap = require('../wrap');
 
 function root(h, node) {
-  return h(node, 'root', wrap.optional(all(h, node)));
+  var children = all(h, node);
+
+  if (h.document || wrap.needed(children)) {
+    children = wrap(children);
+  }
+
+  return h(node, 'root', children);
 }

index.js

@@ -12,6 +12,7 @@ function toMDAST(tree, options) {
 
   h.handlers = xtend(handlers, settings.handlers || {});
   h.augment = augment;
+  h.document = settings.document;
 
   return one(h, minify(tree), null);
 

tests/fixtures/implicit-paragraphs/index.html

@@ -11,3 +11,5 @@ <h1>An <em>explicit</em> paragraph</h1>
   <h1>Heading</h1>
   Another <em>implicit</em> paragraph.
 </blockquote>
+
+<em>Emphasis</em>, <strong>importance</strong>, and <s>strikethrough</s>.

tests/fixtures/implicit-paragraphs/index.md

@@ -7,3 +7,5 @@ An **implicit** paragraph.
 > # Heading
 >
 > Another _implicit_ paragraph.
+
+_Emphasis_, **importance**, and ~~strikethrough~~.

tests/index.js

@@ -189,3 +189,38 @@ test('handlers option', function (t) {
 
   t.end();
 });
+
+test('document', function (t) {
+  var tree = u('root', [
+    h('b', 'Importance'),
+    u('text', ' and '),
+    h('i', 'emphasis'),
+    u('text', '.')
+  ]);
+
+  t.deepEqual(
+    toMDAST(tree),
+    u('root', [
+      u('strong', [u('text', 'Importance')]),
+      u('text', ' and '),
+      u('emphasis', [u('text', 'emphasis')]),
+      u('text', '.')
+    ]),
+    'should infer document if not needed'
+  );
+
+  t.deepEqual(
+    toMDAST(tree, {document: true}),
+    u('root', [
+      u('paragraph', [
+        u('strong', [u('text', 'Importance')]),
+        u('text', ' and '),
+        u('emphasis', [u('text', 'emphasis')]),
+        u('text', '.')
+      ])
+    ]),
+    'should support an explitic `document: true`'
+  );
+
+  t.end();
+});

wrap.js

@@ -2,7 +2,7 @@
 
 module.exports = wrap;
 
-wrap.optional = optional;
+wrap.needed = needed;
 
 var is = require('unist-util-is');
 
@@ -56,11 +56,6 @@ function wrap(nodes) {
   return result;
 }
 
-/* Optionally wrap `nodes`, if `needed`. */
-function optional(nodes) {
-  return needed(nodes) ? wrap(nodes) : nodes;
-}
-
 /* Check if there are non-inline MDAST nodes returned.
  * This is needed if a fragment is given, which could just be
  * a sentence, and doesn’t need a wrapper paragraph. */