feat: Support frontmatter in docs

lib/transform.js

@@ -207,29 +207,37 @@ exports = module.exports = function transform(content, mode, maxHeaderLevel, min
   if (!(tocs.positions?.length > 0) && updateOnly) {
     return { transformed: false };
   }
-  
+
   var startLine = 0;
-  var frontMatter = false;
-  var frontMatterDelimiters = ['+++', ';;;'];
+  var startPos = 0;
   var firstChild = docNodes.children.length > 0 ? docNodes.children[0] : undefined;
-  if (firstChild?.type === 'Yaml') {
-    frontMatter = true;
-  } else if (firstChild?.type === 'Paragraph') {
-    frontMatter = frontMatterDelimiters.some(d =>
-      firstChild.raw.startsWith(d) && firstChild.raw.trim().endsWith(d));
-  }
+  var frontMatter = firstChild?.type === 'Json' || firstChild?.type === 'Toml' || firstChild?.type === 'Yaml';
 
   var hasBody = docNodes.children.length > (frontMatter ? 1 : 0);
   if (frontMatter && hasBody) {
     startLine = docNodes.children[1].loc.start.line - 1;
+    startPos = docNodes.children[1].range[0];
   }
   // force it on to the next line after current content
   else if (frontMatter) {
     startLine = docNodes.children[0].loc.end.line;
+    startPos = docNodes.range[1] + 1;
+  }
+
+  // adds in the empty line between end of content & new toc if missing
+  if (frontMatter && docNodes.range[1] === docNodes.children[0].range[1]) {
+    startPos = startPos + eol.length;
+    content += eol;
   }
 
+  // if there is no empty line between front matter & content add one
+  if (frontMatter && hasBody && docNodes.children[0].loc.end.line + 1 == docNodes.children[1].loc.start.line) {
+    content = content.substring(0, startPos) + eol + content.substring(startPos);
+    startPos = startPos + eol.length;
+  }
+
   if (!(tocs.positions?.length > 0)) {
-    var insertPos = 0;
+    var insertPos = startPos;
     tocs.positions = [{
       end: {
         range: [insertPos, insertPos],
@@ -244,7 +252,7 @@ exports = module.exports = function transform(content, mode, maxHeaderLevel, min
   }
 
   var tocPosition = tocs.positions[0];
-  var tocableStart = !processAll ? tocPosition.end.range[1] : 0;
+  var tocableStart = !processAll ? tocPosition.end.range[1] : startPos;
   var headers = getMarkdownHeaders(docNodes, tocableStart, maxHeaderLevel, minHeaderLevel)
     .concat(getHtmlHeaders(docNodes, tocableStart, maxHeaderLevelHtml, minHeaderLevel));
 

package.json

@@ -17,7 +17,7 @@
   "main": "doctoc.js",
   "bin": "doctoc.js",
   "dependencies": {
-    "@textlint/markdown-to-ast": "^15.5.2",
+    "@textlint/markdown-to-ast": "^15.6.0",
     "anchor-markdown-header": "^0.8.4",
     "htmlparser2": "^7.2.0",
     "loglevel": "^1.9.2",

test/fixtures/readme-frontmatter-blank.md

@@ -0,0 +1,3 @@
+---
+title: Yaml Front Matter
+---

test/fixtures/readme-frontmatter-existing.md

@@ -0,0 +1,16 @@
+---
+title: Yaml Front Matter
+---
+
+# Title
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Title](#title)
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Heading
+
+Your regular Markdown content follows...

test/fixtures/readme-frontmatter-invalid.md

@@ -0,0 +1,7 @@
++++
+title: Invalid Front Matter
+|||
+
+# Heading
+
+Your regular Markdown content follows...

test/fixtures/readme-frontmatter-json.md

@@ -0,0 +1,7 @@
+;;;
+title: JSON Front Matter
+;;; 
+
+# Heading
+
+Your regular Markdown content follows...

test/fixtures/readme-frontmatter-toml.md

@@ -0,0 +1,7 @@
++++
+title: TOML Front Matter
++++ 
+
+# Heading
+
+Your regular Markdown content follows...

test/fixtures/readme-frontmatter-yaml.md

@@ -0,0 +1,7 @@
+---
+title: Yaml Front Matter
+---
+
+# Heading
+
+Your regular Markdown content follows...

test/transform-frontmatter.js

@@ -0,0 +1,188 @@
+'use strict';
+/*jshint asi: true */
+
+var test = require('tap').test
+  , transform = require('../lib/transform')
+
+test('\ngiven a file that includes Json frontmatter', function (t) {
+  var content = require('fs').readFileSync(__dirname + '/fixtures/readme-frontmatter-json.md', 'utf8');
+  var res = transform(content);
+
+  t.same(
+      res.data
+    , [ ';;;',
+        'title: JSON Front Matter',
+        ';;; ',
+        '',
+        '<!-- START doctoc generated TOC please keep comment here to allow auto update -->',
+        '<!-- DON\'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->',
+        '**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*',
+        '',
+        '- [Heading](#heading)',
+        '',
+        '<!-- END doctoc generated TOC please keep comment here to allow auto update -->',
+        '',
+        '# Heading',
+        '',
+        'Your regular Markdown content follows...',
+        '' ].join('\n')  
+    , 'generates correct toc for file with Json frontmatter'
+  )
+
+  t.end()
+})
+
+test('\ngiven a file that includes Toml frontmatter', function (t) {
+  var content = require('fs').readFileSync(__dirname + '/fixtures/readme-frontmatter-toml.md', 'utf8');
+  var res = transform(content);
+
+  t.same(
+      res.data
+    , [ '+++',
+        'title: TOML Front Matter',
+        '+++ ',
+        '',
+        '<!-- START doctoc generated TOC please keep comment here to allow auto update -->',
+        '<!-- DON\'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->',
+        '**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*',
+        '',
+        '- [Heading](#heading)',
+        '',
+        '<!-- END doctoc generated TOC please keep comment here to allow auto update -->',
+        '',
+        '# Heading',
+        '',
+        'Your regular Markdown content follows...',
+        '' ].join('\n')  
+    , 'generates correct toc for file with Toml frontmatter'
+  )
+
+  t.end()
+})
+
+test('\ngiven a file that includes yaml frontmatter', function (t) {
+  var content = require('fs').readFileSync(__dirname + '/fixtures/readme-frontmatter-yaml.md', 'utf8');
+  var res = transform(content);
+
+  t.same(
+      res.data
+    , [ '---',
+        'title: Yaml Front Matter',
+        '---',
+        '',
+        '<!-- START doctoc generated TOC please keep comment here to allow auto update -->',
+        '<!-- DON\'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->',
+        '**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*',
+        '',
+        '- [Heading](#heading)',
+        '',
+        '<!-- END doctoc generated TOC please keep comment here to allow auto update -->',
+        '',
+        '# Heading',
+        '',
+        'Your regular Markdown content follows...',
+        '' ].join('\n')  
+    , 'generates correct toc for file with yaml frontmatter'
+  )
+
+  t.end()
+})
+
+test('\ngiven a file that includes invalid frontmatter', function (t) {
+  var content = require('fs').readFileSync(__dirname + '/fixtures/readme-frontmatter-invalid.md', 'utf8');
+  var res = transform(content);
+
+  t.same(
+      res.data
+    , [ '<!-- START doctoc generated TOC please keep comment here to allow auto update -->',
+        '<!-- DON\'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->',
+        '**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*',
+        '',
+        '- [Heading](#heading)',
+        '',
+        '<!-- END doctoc generated TOC please keep comment here to allow auto update -->',
+        '',
+        '+++',
+        'title: Invalid Front Matter',
+        '|||',
+        '',
+        '# Heading',
+        '',
+        'Your regular Markdown content follows...',
+        '' ].join('\n')  
+    , 'generates correct toc for file with invalid frontmatter'
+  )
+
+  t.end()
+})
+
+test('\ngiven a file that has only yaml frontmatter and empty line', function (t) {
+  var content = require('fs').readFileSync(__dirname + '/fixtures/readme-frontmatter-blank.md', 'utf8');
+  var res = transform(content.trim() + '\n');
+
+  t.same(
+      res.data
+    , [ '---',
+        'title: Yaml Front Matter',
+        '---',
+        '',
+        '<!-- START doctoc generated TOC please keep comment here to allow auto update -->',
+        '<!-- DON\'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->',
+        '<!-- END doctoc generated TOC please keep comment here to allow auto update -->',
+        '' ].join('\n')  
+    , 'generates correct toc for file with only yaml frontmatter'
+  )
+
+  t.end()
+})
+
+test('\ngiven a file that has only yaml frontmatter and no trailing whitespace', function (t) {
+  var content = require('fs').readFileSync(__dirname + '/fixtures/readme-frontmatter-blank.md', 'utf8');
+  var res = transform(content.trim());
+
+  t.same(
+      res.data
+    , [ '---',
+        'title: Yaml Front Matter',
+        '---',
+        '',
+        '<!-- START doctoc generated TOC please keep comment here to allow auto update -->',
+        '<!-- DON\'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->',
+        '<!-- END doctoc generated TOC please keep comment here to allow auto update -->',
+        '' ].join('\n')  
+    , 'generates correct toc for file with only yaml frontmatter'
+  )
+
+  t.end()
+})
+
+test('\ngiven a file that includes yaml frontmatter and process all', function (t) {
+  var content = require('fs').readFileSync(__dirname + '/fixtures/readme-frontmatter-existing.md', 'utf8');
+  var res = transform(content, undefined, undefined, undefined, undefined, undefined, undefined, undefined, true);
+
+  t.same(
+      res.data
+    , [ '---',
+        'title: Yaml Front Matter',
+        '---',
+        '',
+        '# Title',
+        '',
+        '<!-- START doctoc generated TOC please keep comment here to allow auto update -->',
+        '<!-- DON\'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->',
+        '**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*',
+        '',
+        '- [Title](#title)',
+        '  - [Heading](#heading)',
+        '',
+        '<!-- END doctoc generated TOC please keep comment here to allow auto update -->',
+        '',
+        '## Heading',
+        '',
+        'Your regular Markdown content follows...',
+        '' ].join('\n')  
+    , 'generates correct toc for file with yaml frontmatter'
+  )
+
+  t.end()
+})

test/transform.js

@@ -12,10 +12,23 @@ function check(md, anchors, mode, maxHeaderLevel, minHeaderLevel, minTocItems, t
     // build the expected content
     eol = eol || '\n';
     var pragma = contentGenerator.pragmaMarkers(syntax || 'md');
+    var body = '';
+    var doc = '';
+    var tag = md.substring(0, 3);
+    const tags = ['---', ';;;', '+++'];
+    if (tags.includes(tag) && md.indexOf(tag, 3) > 0) {
+      var pos = md.indexOf(tag, 3) + 3 + eol.length; // find the closing tag and skip that line
+      body = md.substring(pos);
+      if (body.startsWith(eol)) { body = body.substring(eol.length); }
+      doc = md.substring(0, pos) + eol;
+    }
+    else {
+      body = md;
+    }
     var contents =  anchors.trimEnd();
     if (contents != '') { contents += eol; }
     var toc = pragma.start + eol + anchors.trimEnd() + (anchors ? eol + eol : '') + pragma.end;
-    var doc = res.wrappedToc + eol + eol + md;
+    doc = doc + res.wrappedToc + eol + eol + body;
 
     t.ok(res.transformed, 'transforms it');
     t.same(res.toc, contents, 'generates correct toc contents');
@@ -1065,6 +1078,29 @@ check(
     , 'mdx'
 )
 
+check(
+  [ '---'
+  , ''
+  , '# Real Heading'
+  , 'body'
+  ].join('\n')
+, [ '**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*\n\n'
+  , '- [Real Heading](#real-heading)\n\n\n'
+  ].join('')
+)
+
+check(
+  [ '---'
+  , 'title: Yaml'
+  , '---'
+  , '# H'
+  , 'body'
+  ].join('\n')
+, [ '**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*\n\n'
+  , '- [H](#h)\n\n\n'
+  ].join('')
+)
+
 test('should use <!-- --> comments if syntax=md', function (t) {
     var res = transform(
                   [ '# My Module'