slug

README

go-slug

URL-safe slug generator for Go. Handles Unicode, configurable, zero dependencies.

Installation

go get github.com/philiprehberger/go-slug

Usage

Basic

import "github.com/philiprehberger/go-slug"

slug.Make("Hello, World!")        // "hello-world"
slug.Make("Über Café & Naïve")   // "uber-cafe-and-naive"
slug.Make("Item 42")              // "item-42"

Options

// Custom separator
s := slug.New(slug.WithSeparator("_"))
s.Make("Hello World") // "hello_world"

// Max length (truncates at word boundary)
s = slug.New(slug.WithMaxLen(10))
s.Make("this is a long title") // "this-is-a"

// Custom substitutions (applied before transliteration)
s = slug.New(slug.WithCustomSubs(map[string]string{
    "C++": "cpp",
    "C#":  "csharp",
}))
s.Make("Learning C++ and C#") // "learning-cpp-and-csharp"

Unique Slugs

existing := map[string]bool{
    "hello-world":   true,
    "hello-world-2": true,
}

result := slug.Unique("Hello World", func(s string) bool {
    return existing[s]
})
// result: "hello-world-3"

API

Function / Type	Description
Make(s string) string	Generate a slug with default settings
Unique(input string, exists func(string) bool) string	Generate a unique slug with default settings
New(opts ...Option) *Slugger	Create a configured slugger
(*Slugger) Make(input string) string	Generate a slug with configured options
(*Slugger) Unique(input string, exists func(string) bool) string	Generate a unique slug with configured options
WithSeparator(sep string) Option	Set the word separator (default: "-")
WithMaxLen(n int) Option	Set max slug length with word-boundary truncation
WithCustomSubs(subs map[string]string) Option	Set custom string substitutions

Development

go test ./...
go vet ./...

License

MIT

Documentation

Overview

Package slug provides URL-safe slug generation from strings.

It handles Unicode transliteration, configurable separators, max length truncation at word boundaries, and unique slug generation.

Index

• func Make(s string) string
• func Unique(input string, exists func(slug string) bool) string
• type Option
  • func WithCustomSubs(subs map[string]string) Option
  • func WithMaxLen(n int) Option
  • func WithSeparator(sep string) Option
• type Slugger
  • func New(opts ...Option) *Slugger
  • func (sl *Slugger) Make(input string) string
  • func (sl *Slugger) Unique(input string, exists func(slug string) bool) string

Functions

func Make

func Make(s string) string

Make generates a URL-safe slug from the given string using default settings. It transliterates Unicode to ASCII, lowercases the result, replaces non-alphanumeric characters with hyphens, collapses consecutive hyphens, and trims hyphens from the start and end.

func Unique

func Unique(input string, exists func(slug string) bool) string

Unique generates a unique slug by appending -2, -3, etc. if the slug already exists. The exists function should return true if the slug is already taken.

Types

type Option

type Option func(*Slugger)

Option configures a Slugger.

func WithCustomSubs

func WithCustomSubs(subs map[string]string) Option

WithCustomSubs sets custom string substitutions that are applied before transliteration. Keys are matched case-sensitively.

func WithMaxLen

func WithMaxLen(n int) Option

WithMaxLen sets the maximum length of the generated slug. The slug is truncated at the last word boundary (separator) before maxLen. A value of 0 means no limit.

func WithSeparator

func WithSeparator(sep string) Option

WithSeparator sets the separator character used between words. The default separator is "-".

type Slugger

type Slugger struct {
	// contains filtered or unexported fields
}

Slugger generates URL-safe slugs with configurable options.

func New

func New(opts ...Option) *Slugger

New creates a new Slugger with the given options.

func (*Slugger) Make

func (sl *Slugger) Make(input string) string

Make generates a URL-safe slug from the given string.

The algorithm is:

1. Apply custom substitutions
2. Transliterate Unicode to ASCII
3. Lowercase
4. Replace any non [a-z0-9] with separator
5. Collapse consecutive separators
6. Trim separators from start/end
7. If maxLen is set, truncate at word boundary

func (*Slugger) Unique

func (sl *Slugger) Unique(input string, exists func(slug string) bool) string

Unique generates a unique slug by appending -2, -3, etc. if the base slug already exists. The exists function should return true if a given slug is already taken.