github-slugger

What is github-slugger?

The github-slugger npm package generates GitHub-style slugs from strings. These slugs are often used in URLs, markdown headers, and anywhere else where a simplified, URL-friendly identifier for a string is useful. It ensures uniqueness of the slugs within the same document or context by appending incrementing numbers when duplicates are generated.

What are github-slugger's main functionalities?

Generate a slug from a string

This feature allows you to convert any string into a slug that is URL-friendly and resembles the slugs GitHub generates for markdown headers.

"const GithubSlugger = require('github-slugger');
const slugger = new GithubSlugger();
console.log(slugger.slug('Hello World')); // Outputs: 'hello-world'"

Generate unique slugs within the same instance

This demonstrates how github-slugger ensures uniqueness by appending incrementing numbers to slugs generated from identical strings within the same instance.

"const GithubSlugger = require('github-slugger');
const slugger = new GithubSlugger();
console.log(slugger.slug('Hello World')); // Outputs: 'hello-world'
console.log(slugger.slug('Hello World')); // Outputs: 'hello-world-1'"

Resetting the slugger

This feature shows how to reset the internal state of the slugger instance, allowing for the reuse of slugs that were previously incremented.

"const GithubSlugger = require('github-slugger');
const slugger = new GithubSlugger();
slugger.slug('Hello World');
slugger.reset();
console.log(slugger.slug('Hello World')); // Outputs: 'hello-world' again, after reset"

Other packages similar to github-slugger

slugify

slugify is a similar package that converts strings into URL slugs. Compared to github-slugger, slugify offers more customization options, such as the ability to specify replacement characters, but it does not automatically handle uniqueness within the same context.

uslug

uslug is another package for generating slugs from strings. It focuses on creating slugs that are safe for URLs and readable. Unlike github-slugger, uslug does not automatically append numbers to ensure uniqueness, but it provides options for allowing certain special characters to be included.

README

github-slugger

Generate a slug just like GitHub does for markdown headings. It also ensures slugs are unique in the same way GitHub does it. The overall goal of this package is to emulate the way GitHub handles generating markdown heading anchors as close as possible.

This project is not a markdown or HTML parser: passing alpha *bravo* charlie or alpha <em>bravo</em> charlie doesn’t work. Instead pass the plain text value of the heading: alpha bravo charlie.

Install

npm install github-slugger

Usage

import GithubSlugger from 'github-slugger'

const slugger = new GithubSlugger()

slugger.slug('foo')
// returns 'foo'

slugger.slug('foo')
// returns 'foo-1'

slugger.slug('bar')
// returns 'bar'

slugger.slug('foo')
// returns 'foo-2'

slugger.slug('Привет non-latin 你好')
// returns 'привет-non-latin-你好'

slugger.slug('😄 emoji')
// returns '-emoji'

slugger.reset()

slugger.slug('foo')
// returns 'foo'

Check test/fixtures.json for more examples.

If you need, you can also use the underlying implementation which does not keep track of the previously slugged strings (not recommended):

import GithubSlugger, {slug} from 'github-slugger'

slug('foo bar baz')
// returns 'foo-bar-baz'

slug('foo bar baz')
// returns the same slug 'foo-bar-baz' because it does not keep track

Contributing

Contributions welcome! Please read the contributing guidelines first.

License

ISC

Changelog

2.0.0 2022-10-27

• Use ESM breaking: please read this guide
• Add types breaking: tiny chance of breaking, use a new version of TS and it’ll work