feat: Support frontmatter in docs

[thompson-tomo]

Closes #279

Insert toc after front matter content to ensure front matter remains valid.

[AndrewSouthpaw]

• Looks like it crashes for an empty file
• Crashes for a file with only the YAML frontmatter and no other content
• Same for JSON
• Probably add a test for re-running on a TOC'ed frontmatter file?
• Test case with processAll?
• The startsWith/endsWith check on .raw breaks if the closing delimiter has trailing whitespace, e.g. "+++\ntitle: test\n+++ \n"

[thompson-tomo]

@AndrewSouthpaw i believe all the additional scenarios are being catered for now with the additional tests as well as robustness improvements

[AndrewSouthpaw]

two small notes, looks just about ready!

[AndrewSouthpaw]

Nice! It looks like there's one regression worth addressing here. The frontmatter doc/body split in check() above assumes the
closing delimiter is followed by exactly one blank line:

var pos = md.indexOf(tag,3) + 3 + 2 * eol.length;

With anything other than one blank line, pos is wrong (here, 0 blank lines drags the first char of the next line into the doc segment).

Separately, md.substring(0, 3) matches any 3-char prefix in ['---', ';;;', '+++'], so a horizontal-rule "---" at the top of a doc is misclassified as frontmatter and falls into the same broken path. Both should round-trip once the helper scans for the next non-blank line after a verified closing tag.

A couple sample checks, which both fail right now:

// 0 blank lines after the closing delimiter
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('')
)

// "---" at the top is a horizontal rule, not frontmatter — helper false-positive
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('')
)

I was inclined to let it be a follow-up, as I think it's maybe unlikely for docs to have a leading --- without it being frontmatter... But it would be quite unfortunate if they did. Let's do one more round and address this as in scope to the PR.

[thompson-tomo]

Thanks @AndrewSouthpawfor picking up those cases. I have added those checks and am ensuring they are passing.

[Copilot]

Pull request overview

Adds support for documents that start with front matter by ensuring the generated TOC is inserted after the front matter region (keeping the front matter block valid), and expands the test suite to cover YAML/TOML/JSON-style delimiters.

Changes:

• Adjust TOC insertion and header scanning start positions to account for detected front matter.
• Add a dedicated front matter test suite and fixtures (yaml/toml/json/invalid/blank/existing-TOC cases).
• Update the shared transform test helper to build expected docs with TOC placed after front matter.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

File	Description
lib/transform.js	Detect front matter and shift insertion/header-processing offsets to begin after it.
test/transform.js	Update test helper to build expected output with TOC after front matter; add a couple front matter-related checks.
test/transform-frontmatter.js	New tests validating TOC placement with multiple front matter styles and edge cases.
test/fixtures/readme-frontmatter-*.md	New fixtures used by the new front matter tests.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[thompson-tomo]

Good news with textlint/textlint#2015 we can natively detect know if json/toml, hence ci broken for package to be updated.