Github-slugger is an npm package designed to generate slugs similar to how GitHub does for markdown headings. Its function is not limited to slug generation but it also ensures the uniqueness of these slugs, paralleling the way GitHub does it. It's worth noting that github-slugger is not a markdown or HTML parser, therefore, it operates on the plain text value of the heading and not on encoded text. Its primary objective is to replicate the way GitHub manages the creation of markdown heading anchors as meticulously as possible.
To use github-slugger, first install the package in your project by running npm install github-slugger. You can then import it into your JavaScript files using import GithubSlugger from 'github-slugger'. To generate a slug, instantiate GithubSlugger and use the slug() function of the instance.
Here's how:
import GithubSlugger from 'github-slugger'
const slugger = new GithubSlugger()
slugger.slug('foo') // returns 'foo'
slugger.slug('foo') // returns 'foo-1' (as it ensures uniqueness)
slugger.slug('bar') // returns 'bar'
slugger.slug('Привет non-latin 你好') // returns 'привет-non-latin-你好' (handles non-latin texts)
slugger.slug('😄 emoji') // returns '-emoji' (handles emojis)
This instance will remember the slugs it has generated. If you want to reset it, simply call the reset() function. Here's an example:
slugger.reset()
slugger.slug('foo') // now it returns 'foo' again
One can also use the underlying slug function, which does not keep track of previous entries. However, this is not recommended, and should be done as follows:
import GithubSlugger, {slug} from 'github-slugger'
slug('foo bar baz') // returns 'foo-bar-baz'
The documentation for github-slugger is found in its readme file on GitHub. Visit GithubSlugger's GitHub repository for detailed usage instructions and examples. The test/fixtures.json file, within the same repository, contains more examples on usage. Please refer to this documentation for any further clarification or information.
