slug

gosimple/slug is a small, focused Go library for generating URL-friendly slugs from arbitrary Unicode input. Rather than simply stripping non-ASCII characters, it transliterates them first — accented Latin letters, Cyrillic, Greek, and CJK characters are converted to their closest ASCII equivalents via the companion gosimple/unidecode library, then the result is lowercased, stripped of disallowed symbols, and normalized so dashes and underscores never sit at the edges of the output.

The package exposes two entry points, Make and MakeLang, alongside a set of package-level options (Lowercase, MaxLength, EnableSmartTruncate, CustomSub, CustomRuneSub, DisableMultipleDashTrim, DisableEndsTrim, AppendTimestamp) that let callers customize behavior without any configuration struct or builder — a single slug.Make("text") call covers the common case, while the exported vars cover everything else, including custom string and rune substitution maps and smart word-boundary truncation for length-constrained slugs.

What You Get

• Make(s string) string — one-call slug generation using English substitution rules
• MakeLang(s, lang string) string — same generation with a specific language’s substitution table (ISO 639-1/639-3 codes for bg, cs, de, en, es, fi, fr, el, hu, id, it, kk, nb, nl, nn, pl, pt/pt-br, ro, sl, sv, tr)
• Package-level CustomSub/CustomRuneSub maps for project-specific string and rune replacements applied before language substitution
• MaxLength with EnableSmartTruncate to cap slug length at a word boundary instead of cutting mid-word
• AppendTimestamp to auto-suffix generated slugs with a Unix timestamp for uniqueness
• IsSlug(text string) bool validator to check whether an arbitrary string already conforms to the slug format

Common Use Cases

• Generating SEO-friendly URL paths from article or product titles at write time in a CMS or e-commerce backend
• Deriving safe, collision-resistant filenames from user-supplied upload names
• Normalizing multilingual user input (names, tags, search terms) into consistent ASCII keys for database lookups or caching
• Validating that externally supplied slugs match the expected format before using them in routing

Under The Hood

Architecture The package is a single flat unit with no internal layering: slug.go holds the entire public API (Make, MakeLang, Substitute, SubstituteRune, smartTruncate, IsSlug) as package-level functions operating over package-level mutable configuration variables, languages_substitution.go supplies per-language rune substitution maps that are merged with a shared defaultSub table in an init() function at package load time, and doc.go carries only the package-level doc comment shown on pkg.go.dev. There are no structs, interfaces, or dependency injection — MakeLang is a linear transform pipeline (trim → custom rune/string substitution → language-specific rune substitution → Unicode-to-ASCII transliteration via unidecode → lowercase → charset stripping via regex → dash normalization → edge trim → optional smart truncation → optional timestamp suffix), and it is the single place all behavior actually happens.

Tech Stack A standard Go module (go.mod targets Go 1.11 for broad compatibility) with exactly one runtime dependency, github.com/gosimple/unidecode, which performs the actual Unicode-to-ASCII transliteration table lookups. There is no web framework, database, or build tooling beyond the standard go build/go test toolchain — CI (GitHub Actions) runs the test suite against two Go versions with the race detector and coverage enabled, uploads results to Codecov, and runs go vet plus staticcheck as a separate lint job.

Code Quality Test coverage is extensive relative to the package’s size: slug_test.go contains ten table-driven test functions covering diacritics across many languages, punctuation and symbol stripping, custom substitution maps, smart truncation, IsSlug validation, and specific regression cases (one test case is annotated as covering a numbered historical bug involving a 4-byte Unicode rune). CI enforces go vet, staticcheck, and race-detector test runs with coverage reporting on every push. None of the public functions return errors — the API is pure string-in/string-out, so error handling is not applicable in the typical sense; edge cases like empty input are handled with explicit guard conditions rather than panics. Naming follows idiomatic Go conventions throughout.

API Design The public surface is deliberately minimal — Make and MakeLang cover the overwhelming majority of use cases with zero configuration, and every additional behavior (case handling, length limits, custom substitutions, uniqueness suffixes) is exposed as a plain package-level variable rather than a builder or options struct, so the entire integration for the common case is a single function call. The README documents every option in one copy-paste example block. The tradeoff is that this configuration model uses shared mutable package state rather than per-call options, which is a real limitation for callers who need different settings across concurrent or isolated call sites within the same process.