NFE: add dry run capabilities to default slugger

[flouc001]

Marked version: 1.1.0

Markdown flavor: n/a

Description

This PR adds a feature that allows the developer to use the default slugger without updating the internal accumulator. I have seen a use case for this when developers are implementing their own custom renderers. For example, see this function in the TC39 temporal-proposal repository. The changes made can be summarized as:

• Extends the default slugger with the ability to generate slug text without trigger internal communication.
• Separates slugger responsibilities into methods for re-use.

Contributor

• Test(s) exist to ensure functionality and minimize regression (if no tests added, list tests covering this PR); or,
• no tests required for this PR.
• If submitting new feature, it has been documented in the appropriate places.

Committer

In most cases, this should be a different person than the contributor.

• Draft GitHub release notes have been updated.
• CI is green (no forced merge required).
• Merge PR

[vercel]

This pull request is being automatically deployed with Vercel (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://vercel.com/markedjs/markedjs/8t7vm3sc9
✅ Preview: https://markedjs-git-fork-flouc001-nfe-dry-run-slug.markedjs.vercel.app

[flouc001]

@UziTech I've made the changes you requested, the only thing I wasn't sure on was how you wanted the option documented in the code. I've added basic JSDoc but I can't see an example of it being used similarly anywhere else in the codebase so happy to take it out 👍

[UziTech]

JSDoc works fine. Documentation in the code could definitely be better.

[joshbruce]

Not that it has too and it would be good to know.

Does this affect special characters and asian character sets as that's been a topic: #664

Or, is it specifically giving the ability for a developer to intervene and verify themselves??

In either case, I will approve but not merge as this one feels a bit deeper than my understanding at present.

[flouc001]

@joshbruce

Does this affect special characters and asian character sets as that's been a topic: #664

This code should not affect how the heading id is actually generated so there will be no deviation from default behaviour on that front.

Or, is it specifically giving the ability for a developer to intervene and verify themselves??

Exactly, this option is all about giving control to the developer who, for whatever reason, may want to generate heading ids without incrementing the Slugger's seen counter. At the moment there is no way to generate the heading id without causing the Slugger to mutate that internal counter.

[flouc001]

@styfle I've added the test you recommended and committed all outstanding suggestions 👍

[styfle]

Thanks!

[github-actions]

🎉 This PR is included in version 1.1.2 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀