Generating URL-Safe Slugs: github-slugger vs slug vs slugify vs url-slug

When building web applications, you often need to turn titles, names, or user input into clean, URL-friendly strings — known as "slugs." These are used for permalinks, anchor IDs, file names, or route parameters. The four packages under review — github-slugger, slug, slugify, and url-slug — all aim to solve this problem, but they differ significantly in scope, behavior, and suitability for real-world scenarios.

⚠️ Deprecation Notice: url-slug Is Not Safe for New Projects

First, a critical note: url-slug is officially deprecated. According to its npm page, the package is no longer maintained and should not be used in new codebases. While it once provided a chainable API for slug creation, it lacks updates, security patches, and modern Unicode support. We’ll include it in comparisons for completeness, but do not choose it — opt for slug or slugify instead.

// ❌ Avoid: url-slug (deprecated)
// const slug = require('url-slug');
// const result = slug('Hello World').create(); // Not recommended

🔤 Core Behavior: How Each Package Handles Input

Let’s compare how each library transforms the same inputs, especially edge cases involving special characters, duplicates, and non-Latin scripts.

Basic ASCII Input

All packages handle simple English text similarly:

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

// slug
const slug = require('slug');
console.log(slug('Hello World')); // 'hello-world'

// slugify
const slugify = require('slugify');
console.log(slugify('Hello World')); // 'hello-world'

// url-slug (deprecated — shown for reference only)
// console.log(slug('Hello World').create()); // 'hello-world'

Non-Latin Characters (e.g., German, Russian, Arabic)

This is where differences emerge. Only slug and slugify offer transliteration.

// github-slugger → strips non-ASCII
const gh = new GithubSlugger();
console.log(gh.slug('München')); // 'm-nchen' (loses ü)

// slug → transliterates using charmap
const slug = require('slug');
slug.extend({ 'ü': 'ue' }); // optional customization
console.log(slug('München')); // 'muenchen'

// slugify → built-in transliteration for common chars
const slugify = require('slugify');
console.log(slugify('München')); // 'munchen' (ü → u by default)

// url-slug → limited support, inconsistent
// console.log(slug('München').create()); // likely 'm-nchen' or similar

For Cyrillic:

// github-slugger
console.log(gh.slug('Привет')); // '' (empty — all chars stripped)

// slug
console.log(slug('Привет')); // 'privet' (with proper charmap)

// slugify
console.log(slugify('Привет')); // 'privet' (built-in support)

💡 Note: slug requires explicit charmaps for full i18n coverage, while slugify includes common transliterations by default.

🧩 Uniqueness Handling: Critical for Anchor Links

If you’re generating HTML IDs (e.g., for table-of-contents navigation), duplicate slugs break linking. Only github-slugger tracks state to ensure uniqueness:

// github-slugger
const gh = new GithubSlugger();
console.log(gh.slug('Section'));   // 'section'
console.log(gh.slug('Section'));   // 'section-1'
console.log(gh.slug('Section'));   // 'section-2'

// slug
const slug = require('slug');
console.log(slug('Section')); // 'section'
console.log(slug('Section')); // 'section' (no uniqueness)

// slugify
const slugify = require('slugify');
console.log(slugify('Section')); // 'section'
console.log(slugify('Section')); // 'section' (no uniqueness)

This makes github-slugger the only correct choice for Markdown processors or static site generators that must match GitHub’s behavior exactly.

⚙️ Configuration and Customization

Custom Separators

All active packages allow changing the separator (default: -):

// github-slugger → no separator option; always uses '-'

// slug
console.log(slug('Hello World', { replacement: '_' })); // 'hello_world'

// slugify
console.log(slugify('Hello World', { replacement: '_' })); // 'hello_world'

Lowercasing and Trimming

slug and slugify let you disable lowercasing:

// slug
console.log(slug('Hello World', { lower: false })); // 'Hello-World'

// slugify
console.log(slugify('Hello World', { lower: false })); // 'Hello-World'

// github-slugger → always lowercases

Extending Character Maps

Only slug allows deep customization of transliteration:

const slug = require('slug');
slug.charmap['α'] = 'a';
slug.charmap['β'] = 'b';
console.log(slug('αβγ')); // 'abg' (if γ is supported or stripped)

slugify does not expose its internal charmap for modification.

🧪 Real-World Use Cases

Case 1: Building a Markdown Editor That Matches GitHub

You’re creating a live preview pane that must generate the same anchor IDs as GitHub for synced scrolling or TOC navigation.

✅ Use github-slugger — it’s the only one that replicates GitHub’s algorithm and handles duplicates correctly.

const GithubSlugger = require('github-slugger');
const slugger = new GithubSlugger();

const headings = ['Introduction', 'API', 'API', 'Conclusion'];
const ids = headings.map(h => slugger.slug(h));
// ['introduction', 'api', 'api-1', 'conclusion']

Case 2: Multilingual Blog with User-Generated Titles

Your CMS accepts titles in Spanish, Japanese, Arabic, etc., and you need readable slugs for SEO-friendly URLs.

✅ Use slug — its extensible charmaps and locale support give you full control over transliteration quality.

const slug = require('slug');
// Configure once at app startup
slug.defaults.modes.pretty = {
  replacement: '-',
  symbols: true,
  remove: /[*+~.()"'!:@]/g,
  lower: true,
  charmap: slug.charmap,
  multicharmap: slug.multicharmap
};

console.log(slug('¡Hola, mundo! 👋')); // 'hola-mundo'

Case 3: Simple Admin Dashboard with English-Only Content

You just need to turn form inputs like "Product Name" into clean route params like /products/product-name.

✅ Use slugify — zero dependencies, small footprint, and works out of the box.

const slugify = require('slugify');
app.get('/products/:slug', (req, res) => {
  const product = db.findBySlug(req.params.slug);
});

// When saving
const slug = slugify(userInput, { lower: true });

📊 Summary Table

💡 Final Guidance

• Need GitHub parity? → github-slugger is your only option.
• Building a global app with rich language support? → slug gives you the control you need.
• Just want something simple and reliable for English content? → slugify is lightweight and effective.
• Considering url-slug? → Don’t. It’s deprecated — choose one of the above instead.

In practice, most frontend teams will reach for slugify for general-purpose slugging, while documentation tools and Markdown processors lean on github-slugger. Reserve slug for when you truly need its advanced i18n capabilities.