1 | # slugify
|
2 |
|
3 | > Slugify a string
|
4 |
|
5 | Useful for URLs, filenames, and IDs.
|
6 |
|
7 | It handles most major languages, including [German (umlauts)](https://en.wikipedia.org/wiki/Germanic_umlaut), Vietnamese, Arabic, Russian, [and more](https://github.com/sindresorhus/transliterate#supported-languages).
|
8 |
|
9 | ## Install
|
10 |
|
11 | ```
|
12 | $ npm install @sindresorhus/slugify
|
13 | ```
|
14 |
|
15 | ## Usage
|
16 |
|
17 | ```js
|
18 | import slugify from '@sindresorhus/slugify';
|
19 |
|
20 | slugify('I ♥ Dogs');
|
21 | //=> 'i-love-dogs'
|
22 |
|
23 | slugify(' Déjà Vu! ');
|
24 | //=> 'deja-vu'
|
25 |
|
26 | slugify('fooBar 123 $#%');
|
27 | //=> 'foo-bar-123'
|
28 |
|
29 | slugify('я люблю единорогов');
|
30 | //=> 'ya-lyublyu-edinorogov'
|
31 | ```
|
32 |
|
33 | ## API
|
34 |
|
35 | ### slugify(string, options?)
|
36 |
|
37 | #### string
|
38 |
|
39 | Type: `string`
|
40 |
|
41 | String to slugify.
|
42 |
|
43 | #### options
|
44 |
|
45 | Type: `object`
|
46 |
|
47 | ##### separator
|
48 |
|
49 | Type: `string`\
|
50 | Default: `'-'`
|
51 |
|
52 | ```js
|
53 | import slugify from '@sindresorhus/slugify';
|
54 |
|
55 | slugify('BAR and baz');
|
56 | //=> 'bar-and-baz'
|
57 |
|
58 | slugify('BAR and baz', {separator: '_'});
|
59 | //=> 'bar_and_baz'
|
60 |
|
61 | slugify('BAR and baz', {separator: ''});
|
62 | //=> 'barandbaz'
|
63 | ```
|
64 |
|
65 | ##### lowercase
|
66 |
|
67 | Type: `boolean`\
|
68 | Default: `true`
|
69 |
|
70 | Make the slug lowercase.
|
71 |
|
72 | ```js
|
73 | import slugify from '@sindresorhus/slugify';
|
74 |
|
75 | slugify('Déjà Vu!');
|
76 | //=> 'deja-vu'
|
77 |
|
78 | slugify('Déjà Vu!', {lowercase: false});
|
79 | //=> 'Deja-Vu'
|
80 | ```
|
81 |
|
82 | ##### decamelize
|
83 |
|
84 | Type: `boolean`\
|
85 | Default: `true`
|
86 |
|
87 | Convert camelcase to separate words. Internally it does `fooBar` → `foo bar`.
|
88 |
|
89 | ```js
|
90 | import slugify from '@sindresorhus/slugify';
|
91 |
|
92 | slugify('fooBar');
|
93 | //=> 'foo-bar'
|
94 |
|
95 | slugify('fooBar', {decamelize: false});
|
96 | //=> 'foobar'
|
97 | ```
|
98 |
|
99 | ##### customReplacements
|
100 |
|
101 | Type: `Array<string[]>`\
|
102 | Default: `[
|
103 | ['&', ' and '],
|
104 | ['🦄', ' unicorn '],
|
105 | ['♥', ' love ']
|
106 | ]`
|
107 |
|
108 | Add your own custom replacements.
|
109 |
|
110 | The replacements are run on the original string before any other transformations.
|
111 |
|
112 | This only overrides a default replacement if you set an item with the same key, like `&`.
|
113 |
|
114 | ```js
|
115 | import slugify from '@sindresorhus/slugify';
|
116 |
|
117 | slugify('Foo@unicorn', {
|
118 | customReplacements: [
|
119 | ['@', 'at']
|
120 | ]
|
121 | });
|
122 | //=> 'fooatunicorn'
|
123 | ```
|
124 |
|
125 | Add a leading and trailing space to the replacement to have it separated by dashes:
|
126 |
|
127 | ```js
|
128 | import slugify from '@sindresorhus/slugify';
|
129 |
|
130 | slugify('foo@unicorn', {
|
131 | customReplacements: [
|
132 | ['@', ' at ']
|
133 | ]
|
134 | });
|
135 | //=> 'foo-at-unicorn'
|
136 | ```
|
137 |
|
138 | Another example:
|
139 |
|
140 | ```js
|
141 | import slugify from '@sindresorhus/slugify';
|
142 |
|
143 | slugify('I love 🐶', {
|
144 | customReplacements: [
|
145 | ['🐶', 'dogs']
|
146 | ]
|
147 | });
|
148 | //=> 'i-love-dogs'
|
149 | ```
|
150 |
|
151 | ##### preserveLeadingUnderscore
|
152 |
|
153 | Type: `boolean`\
|
154 | Default: `false`
|
155 |
|
156 | If your string starts with an underscore, it will be preserved in the slugified string.
|
157 |
|
158 | Sometimes leading underscores are intentional, for example, filenames representing hidden paths on a website.
|
159 |
|
160 | ```js
|
161 | import slugify from '@sindresorhus/slugify';
|
162 |
|
163 | slugify('_foo_bar');
|
164 | //=> 'foo-bar'
|
165 |
|
166 | slugify('_foo_bar', {preserveLeadingUnderscore: true});
|
167 | //=> '_foo-bar'
|
168 | ```
|
169 |
|
170 | ### slugifyWithCounter()
|
171 |
|
172 | Returns a new instance of `slugify(string, options?)` with a counter to handle multiple occurences of the same string.
|
173 |
|
174 | #### Example
|
175 |
|
176 | ```js
|
177 | import {slugifyWithCounter} from '@sindresorhus/slugify';
|
178 |
|
179 | const slugify = slugifyWithCounter();
|
180 |
|
181 | slugify('foo bar');
|
182 | //=> 'foo-bar'
|
183 |
|
184 | slugify('foo bar');
|
185 | //=> 'foo-bar-2'
|
186 |
|
187 | slugify.reset();
|
188 |
|
189 | slugify('foo bar');
|
190 | //=> 'foo-bar'
|
191 | ```
|
192 |
|
193 | #### Use-case example of counter
|
194 |
|
195 | If, for example, you have a document with multiple sections where each subsection has an example.
|
196 |
|
197 | ```md
|
198 | ## Section 1
|
199 |
|
200 | ### Example
|
201 |
|
202 | ## Section 2
|
203 |
|
204 | ### Example
|
205 | ```
|
206 |
|
207 | You can then use `slugifyWithCounter()` to generate unique HTML `id`'s to ensure anchors will link to the right headline.
|
208 |
|
209 | ### slugify.reset()
|
210 |
|
211 | Reset the counter
|
212 |
|
213 | #### Example
|
214 |
|
215 | ```js
|
216 | import {slugifyWithCounter} from '@sindresorhus/slugify';
|
217 |
|
218 | const slugify = slugifyWithCounter();
|
219 |
|
220 | slugify('foo bar');
|
221 | //=> 'foo-bar'
|
222 |
|
223 | slugify('foo bar');
|
224 | //=> 'foo-bar-2'
|
225 |
|
226 | slugify.reset();
|
227 |
|
228 | slugify('foo bar');
|
229 | //=> 'foo-bar'
|
230 | ```
|
231 |
|
232 | ## Related
|
233 |
|
234 | - [slugify-cli](https://github.com/sindresorhus/slugify-cli) - CLI for this module
|
235 | - [transliterate](https://github.com/sindresorhus/transliterate) - Convert Unicode characters to Latin characters using transliteration
|
236 | - [filenamify](https://github.com/sindresorhus/filenamify) - Convert a string to a valid safe filename
|