1# slug
 2
 3Package `slug` generate slug from Unicode string, URL-friendly slugify with
 4multiple languages support.
 5
 6[![Go Reference](https://pkg.go.dev/badge/github.com/gosimple/slug.svg)](https://pkg.go.dev/github.com/gosimple/slug)
 7[![Tests](https://github.com/gosimple/slug/actions/workflows/tests.yml/badge.svg)](https://github.com/gosimple/slug/actions/workflows/tests.yml)
 8[![codecov](https://codecov.io/gh/gosimple/slug/branch/master/graph/badge.svg?token=FT2kEZHQW7)](https://codecov.io/gh/gosimple/slug)
 9[![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/gosimple/slug?logo=github&sort=semver)](https://github.com/gosimple/slug/releases)
10
11## Example
12
13```go
14package main
15
16import (
17	"fmt"
18	"github.com/gosimple/slug"
19)
20
21func main() {
22	text := slug.Make("Hellö Wörld хелло ворлд")
23	fmt.Println(text) // Will print: "hello-world-khello-vorld"
24
25	someText := slug.Make("影師")
26	fmt.Println(someText) // Will print: "ying-shi"
27
28	enText := slug.MakeLang("This & that", "en")
29	fmt.Println(enText) // Will print: "this-and-that"
30
31	deText := slug.MakeLang("Diese & Dass", "de")
32	fmt.Println(deText) // Will print: "diese-und-dass"
33
34	slug.Lowercase = false // Keep uppercase characters
35	deUppercaseText := slug.MakeLang("Diese & Dass", "de")
36	fmt.Println(deUppercaseText) // Will print: "Diese-und-Dass"
37
38	slug.CustomSub = map[string]string{
39		"water": "sand",
40	}
41	textSub := slug.Make("water is hot")
42	fmt.Println(textSub) // Will print: "sand-is-hot"
43}
44```
45
46## Design
47
48This library will always returns clean output from any Unicode string
49containing only the following ASCII characters:
50
51* numbers: `0-9`
52* small letters: `a-z`
53* big letters: `A-Z` (only if you set `Lowercase` to `false`)
54* minus sign: `-`
55* underscore: `_`
56
57Minus sign and underscore characters will never appear at the beginning or
58the end of the returned string.
59
60Thanks to context-insensitive transliteration of Unicode characters to ASCII
61output returned string is safe for URL slugs and filenames.
62
63## Requests or bugs?
64
65<https://github.com/gosimple/slug/issues>
66
67If your language is missing you could add it in `languages_substitution.go`
68file.
69
70In case of missing proper Unicode characters transliteration to ASCII you could
71add them to underlying library:
72<https://github.com/gosimple/unidecode>.
73
74## Installation
75
76```shell
77go get -u github.com/gosimple/slug
78```
79
80## Benchmarking
81
82```shell
83go test -run=NONE -bench=. -benchmem -count=6 ./... > old.txt
84# make changes
85go test -run=NONE -bench=. -benchmem -count=6 ./... > new.txt
86
87go install golang.org/x/perf/cmd/benchstat@latest
88
89benchstat old.txt new.txt
90```
91
92## License
93
94The source files are distributed under the
95[Mozilla Public License, version 2.0](http://mozilla.org/MPL/2.0/),
96unless otherwise noted.
97Please read the [FAQ](http://www.mozilla.org/MPL/2.0/FAQ.html)
98if you have further questions regarding the license.