feat: configurable location to insert new toc#346
Conversation
AndrewSouthpaw
left a comment
There was a problem hiding this comment.
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?
|
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. |
|
Thanks @AndrewSouthpaw for the additional test cases & spotting the missing parameter. Please take another look. |
There was a problem hiding this comment.
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-locationCLI option (defaulttop) and plumb it through to the transformer. - Update
lib/transform.jsto 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.
0f121bd to
78dd4e8
Compare
|
@AndrewSouthpaw could you please give this another review. |
|
@AndrewSouthpaw could you circle back to this and the other pr's. Thanks. |
AndrewSouthpaw
left a comment
There was a problem hiding this comment.
So sorry I dropped off there. LGTM. It looks like TOC before h1 in empty markdown is duplicate to TOC before h1 in empty but nbd.
|
No worries at all @AndrewSouthpaw, let's aim for a release once #344 & #353 are merged. |
|
2.5.0 released. |
Closes: #153
Insert toc before first heading used in toc if configured to do so and no toc currently exists