feat: configurable location to insert new toc

[thompson-tomo]

Closes: #153

Insert toc before first heading used in toc if configured to do so and no toc currently exists

[AndrewSouthpaw]

I thought the point of the pragma is to make its location customizable? Seems like that meets the purpose here. Can you come up with a use case where this is limiting you?

[thompson-tomo]

The scenario is when you are not running in update-only mode and a document is discovered which doesn't already have the toc pragma.

With this feature if the document doesn't already have a toc you can specify that the toc is to go before the first h2 heading hence your document will still pass markdownlint.

[thompson-tomo]

Thanks @AndrewSouthpaw for the additional test cases & spotting the missing parameter. Please take another look.

[Copilot]

Pull request overview

Adds a configurable insertion location for newly generated TOCs, addressing the request to place the TOC below a title/intro instead of always at the very top when no TOC exists.

Changes:

• Add --toc-location CLI option (default top) and plumb it through to the transformer.
• Update lib/transform.js to support inserting a new TOC “before the first heading included in the TOC”.
• Add fixture-based tests for markdown headings and HTML <hX> headings, plus README documentation for the new option.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
lib/transform.js	Adds logic to reposition insertion point for new TOCs when toc.location=before.
doctoc.js	Introduces --toc-location arg and includes it in options passed to transform().
README.md	Documents --toc-location and adds it to the README TOC.
test/transform-location.js	Adds coverage for top vs before insertion across markdown + HTML heading scenarios.
test/fixtures/readme-location.md	Fixture: basic markdown headings doc.
test/fixtures/readme-location-hTags.md	Fixture: basic HTML <h1>/<h2> headings doc.

---

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