flet/github-slugger

:octocat: Generate a slug just like GitHub does for markdown headings.

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

github-slugger's Issues

No change log for 1.2.0

Support for german umlaute

German Umlaute characters like 'ö', 'ä', 'ü' should be converted into 'oe', 'ae' or 'ue' to have less problems with different browser support.

Slug contains unwanted hyphen after number

slugger.slug('3d scene')

returns '3-d-scene'

expected '3d-scene'

Accented letters

Hi,

Accented letters do not seem to be converted to their "unaccented" counterpart: Prétérit gives prétérit instead of preterit.

I reckon something identical happens with the apostrophe: L'aoriste gives laoriste which is imperfect, l-aoriste would be better (for both readability and SEO purposes I guess), or worst case aoriste (dropping the l completely, if need be).

What do you think?

Best,

SyntaxError: Cannot use import statement outside a module

I'm working on a project with NextJS, Jest, and Typescript and my tests are not passing because 'github-slugger' is using ESM imports

is it possible to turn the package to use commonjs?

Why this not keep track of prevoius docs if i use it in mongoose schema

for example if i generate a slug and continuously generating then it works fine but if i create new document with same title after a while it not works

Lozenge ◊ not stripped?

It's my own fault for making headings using the lozenge character (◊, U+25CA), but

var GithubSlugger = require("github-slugger")
var slugger = new GithubSlugger();
console.log(slugger.slug('◊sent'))

prints ◊sent instead of sent like GitHub does.

Bug with Unicode

> S = require('github-slugger');
[Function: BananaSlug]
> s = new S
BananaSlug { occurrences: {} }
> s.slug('I ♥ unicode')
'i-♥-unicode'

...but, GitHub slugs that to i--unicode.

Apparently, this used to work fine: github-slugger used to output i--unicode (compare the last Travis build with the one I just triggered).

It’s rather weird that this changed, I’ve got no idea why...

id collision with number in text

var GithubSlugger = require('github-slugger')
var slugger = new GithubSlugger()

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

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

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

This outputs two of the same slugs

Postgres function

Is there anyway to mimic a postgres slugify function for this? I use this slugger on the front-end, but I also want my database to manually created the slugs for updated/inserted data. Ive been trying to make a working copy of this but every resource I have found online usually does not include multiple spaces as dashes and just trims it.

Breaking changes in 1.1

Hello! Greenkeeper just notified me that github-slugger 1.1 broke npm/marky-markdown; the issue is that in 1.0, unicode emoji characters in headings were being stripped out, but now they're being converted to HTML entities.

For example, given ## 😄-😄 unicode hyphen unicode:

• 1.0 rendered --unicode-hyphen-unicode
• 1.1 now renders 😄-😄-unicode-hyphen-unicode

...which has broken a handful of our tests. Is there a way to get the old behavior? Thanks! 👍

Russian letters must not be converted to lowercase

GitHub does not convert russian letters to lowercase, see

https://github.com/bem/bem-method/blob/bem-info-data/faq/faq.ru.md#В-чем-отличие-БЭМ-от-oocss-amcss-smacss-suitcss

as example.

Use something like this

if (!maintainCase) string = string.replace(/([A-Z])+/g, function(s) { return s.toLowerCase() });

instead of

if (!maintainCase) string = string.toLowerCase()

//cc @tadatuta

Expose slugger function

Thanks for this project. In a project of mine, I need the slug function, but the iteration gets in the way. I want to expose the slugger function as a "static" method of the GithubSLugger object. This change would let us use the slugger directly, in this way:

import GithubSlugger from 'GitHub-slugger'

GithubSlugger.slugger('my text to slug')

What do you think?

Expose `maintainCase` to the user

In index.js, there is a conditional to maintain the case but no way to pass that in. It would be great if this were exposed to the user.

I put together an implementation on a fork including tests. I can PR if you're interested.

Handle markup in heading properly

GitHub handles this code

== Why does BEM not recommend using elements within elements (`block__elem1__elem2`)?

as

why-does-bem-not-recommend-using-elements-within-elements-block__elem1__elem2

But github-slugger as

why-does-bem-not-recommend-using-elements-within-elements-codeblock__elem1__elem2code

See https://github.com/bem/bem-method/blob/bem-info-data/faq/faq.en.md#why-does-bem-not-recommend-using-elements-within-elements-block__elem1__elem2

//cc @tadatuta

Any way to add custom replacements?

I want to change + to plus in the slugs. Is there any way to do something like this?

Slugger for Foliant CustomIDs

I want to make a parser for headings in Foliant projects with CustomIDs.

For example # Long heading {#shortref} should result in two refs:

• long-heading
• shortref

Your projects has a basic functionality for this task. I tried to add a possibility to parse CustomdIDs, but it became incompatible with existing version because slugger function returns an array of strings now.

Do you need such functionality in this project or I just can continue my efforts in the fork?

Accents/diacritics should be replaced

Currently I have headings with accents that cause some trouble when linking from another page. For example:

var GithubSlugger = require("github-slugger")
var slugger = new GithubSlugger()
console.log(slugger.slug('Ñacurutú'))

Prints ñacurutú and it should print -acurut-.

I could fix this, if you are interested.

html tags should be removed

Html tags should be removed entirely not just the brackets.

example

slugger.slug('header <em>html</em>')

expected

header-html

actual

header-emhtmlem

Foreign characters not converted properly

e.g. Comment démarrer et configurer le transfert d'e-mails becomes #comment-d%C3%A9marrer-et-configurer-le-transfert-de-mails, which is an unrecognized expression

1.4.0 cannot work as expected with Chinese punctuation

var GithubSlugger = require('github-slugger')
var slugger = new GithubSlugger()

slugger.slug('你好，世界') // 你好世界