or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

GitHub Slugger

GitHub Slugger generates URL-friendly slugs that exactly match GitHub's markdown heading anchor behavior. It provides both stateful and stateless slug generation, with the stateful version automatically handling duplicate slugs by appending incremental numbers.

Package Information

Package Name: github-slugger
Package Type: npm
Language: JavaScript (ES Modules with TypeScript definitions)
Note: Package includes TypeScript definitions (index.d.ts) for type safety
Installation: npm install github-slugger

Core Imports

ES Module (default export is BananaSlug class):

import GithubSlugger from "github-slugger";

With named imports:

import GithubSlugger, { slug } from "github-slugger";

Note: This package is ES Module only ("type": "module" in package.json). CommonJS imports are not supported.

Basic Usage

import GithubSlugger from "github-slugger";

const slugger = new GithubSlugger();

// First occurrence returns base slug
slugger.slug('foo');
// returns 'foo'

// Subsequent occurrences get numbered suffixes
slugger.slug('foo');
// returns 'foo-1'

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

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

// Handles Unicode and special characters
slugger.slug('Привет non-latin 你好');
// returns 'привет-non-latin-你好'

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

// Reset to start fresh
slugger.reset();
slugger.slug('foo');
// returns 'foo'

Architecture

GitHub Slugger is built around two complementary approaches:

Stateful Generation: GithubSlugger class tracks previously generated slugs and ensures uniqueness
Stateless Generation: slug function provides consistent slug generation without tracking
GitHub Compatibility: Uses identical character filtering logic to GitHub's implementation
Unicode Support: Handles international characters, emoji, and special Unicode sequences

Capabilities

Stateful Slug Generation

The primary class for generating unique slugs that match GitHub's behavior.

/**
 * Slugger class that tracks generated slugs to ensure uniqueness
 * Note: The actual class name is BananaSlug, exported as default
 */
class BananaSlug {
  /**
   * Create a new slug class instance
   */
  constructor();

  /**
   * Generate a unique slug, tracking previously generated slugs
   * Repeated calls with the same value will result in different slugs
   * @param value - String of text to slugify
   * @param maintainCase - Keep the current case, otherwise make all lowercase (default: false)
   * @returns A unique slug string
   */
  slug(value: string, maintainCase?: boolean): string;

  /**
   * Reset internal state - forget all previous slugs
   */
  reset(): void;
}

Usage Examples:

import GithubSlugger from "github-slugger";

const slugger = new GithubSlugger();

// Basic slug generation with automatic uniqueness
const headers = ['Introduction', 'Usage', 'Introduction'];
const slugs = headers.map(header => slugger.slug(header));
// Result: ['introduction', 'usage', 'introduction-1']

// Case preservation option
slugger.reset();
const preservedCase = slugger.slug('CaMeLcAsE', true);
// Result: 'CaMeLcAsE'

const lowerCase = slugger.slug('CaMeLcAsE');
// Result: 'camelcase'

Stateless Slug Generation

Standalone function for generating consistent slugs without tracking.

/**
 * Generate a slug without tracking previously generated slugs
 * Repeated calls with the same value will result in the exact same slug
 * @param value - String of text to slugify  
 * @param maintainCase - Keep the current case, otherwise make all lowercase (default: false)
 * @returns A slug string (consistent for same input)
 */
function slug(value: string, maintainCase?: boolean): string;

Usage Examples:

import { slug } from "github-slugger";

// Consistent results for same input
slug('foo bar baz');
// always returns 'foo-bar-baz'

slug('foo bar baz');
// still returns 'foo-bar-baz' (no tracking)

// Case handling
slug('CaMeLcAsE', true);
// returns 'CaMeLcAsE'

slug('CaMeLcAsE');
// returns 'camelcase'

Character Handling

GitHub Slugger implements GitHub's exact character filtering behavior:

Spaces: Converted to hyphens (-)
Unicode Characters: Preserved for most international characters
Emoji: Special handling removes emoji characters but preserves surrounding text
Special Characters: Filtered out using comprehensive Unicode regex
Case Conversion: Converts to lowercase unless maintainCase is true

Error Handling

The library handles edge cases gracefully:

Non-string inputs: Returns empty string for non-string values
Empty strings: Returns empty string
Invalid Unicode: Processes through regex filtering without throwing errors
No exceptions: Normal operation never throws exceptions

Types

// Default export - BananaSlug class (typically imported as GithubSlugger)
class BananaSlug {
  constructor();
  slug(value: string, maintainCase?: boolean): string;
  reset(): void;
}

// Named export - standalone function
function slug(value: string, maintainCase?: boolean): string;

// Export structure
export default BananaSlug;
export { slug };