lim

limax

Node.js module to generate URL slugs. Another one? This one cares about i18n and transliterates non-Latin scripts to conform to the RFC3986 standard. Mostly API-compatible with similar modules.

Showing:

Popularity

Downloads/wk

9.5K

GitHub Stars

460

Maintenance

Last Commit

8mos ago

Contributors

12

Package

Dependencies

3

License

Apache-2.0

Type Definitions

Built-In

Tree-Shakeable

No?

Categories

Readme

limax

(Yet another) Node.js module to generate URL slugs, also known as clean URLs, user-friendly URLs and SEO-friendly URLs.

The difference?

This module extends the fantastic speakingurl module to include Romanisation of Chinese and Japanese scripts.

Give it a string of text in pretty much any major world language and it will convert it to valid characters, conforming to RFC3986, for use within the path element of a URL.

Currently supports, but not limited to, the following scripts:

  • Latin: e.g. English, français, Deutsch, español, português
  • Cyrillic: e.g. Русский язык, български език, українська мова
  • Chinese: e.g. 官话, 吴语 (converts to Latin script using Pinyin with optional tone number)
  • Japanese: e.g. ひらがな, カタカナ (converts to Romaji using Hepburn)

If you already use either the speakingurl or slug modules, you can probably swap in limax without changing the logic in your code.

Oh, and limax is the Latin word for slug.

Install

npm install limax

Usage

import slug from 'limax';

slug(text)

const latin = slug('i ♥ latin'); // i-love-latin
const cyrillic = slug('Я люблю русский'); // ya-lyublyu-russkij
const pinyin = slug('我爱官话'); // wo3-ai4-guan1-hua4
const romaji = slug('私は ひらがな が大好き'); // ha-hiragana-gaki

slug(text, options)

options:

  • replacement: String to replace whitespace with, defaults to - (provides API compatibility with the slug module)
  • separator: String, equivalent to replacement (provides API compatibility with the speakingurl module)
  • lang: String, ISO 639-1 two-letter language code, defaults to auto-detected language
  • tone: Boolean, add tone numbers to Pinyin transliteration of Chinese, defaults to true
  • separateNumbers: Boolean, separate numbers that are within a word, defaults to false
  • separateApostrophes: Boolean, separate apostrophes that are within a word, defaults to false
  • maintainCase: Boolean, maintain the original string's casing, defaults to false
  • custom:
    • Object, custom map for translation, overwrites all i.e. { '&': '#', '*': ' star ' }
    • Array, add chars to allowed charMap
const strich = slug('Ich ♥ Deutsch', {lang: 'de'}); // ich-liebe-deutsch
const unterstreichen1 = slug('Ich ♥ Deutsch', {lang: 'de', replacement: '_'}); // i_liebe_deutsch
const unterstreichen2 = slug('Ich ♥ Deutsch', {lang: 'de', separator: '_'}); // i_liebe_deutsch
const wuYin = slug('弄堂里的菜品赤醬', {tone: false}); // nong-tang-li-di-cai-pin-chi-jiang

// separateNumbers example
const numbersInWord = slug('hello2world'); // hello2world
const numbersSeparated = slug('hello2world', { separateNumbers: true }); // hello-2-world

// separateApostrophes example
const apostrophesInWord = slug('j\'aime'); // jaime
const apostrophesSeparated = slug('j\'aime', { separateApostrophes: true }); // j-aime

// maintainCase example
const caseNotMaintained = slug('HelloWorld'); // helloworld
const caseMaintained = slug('HelloWorld', { maintainCase: true }); // HelloWorld

// custom example
const custom1 = slug('hello.world', { custom: ['.'] }); // hello.world
const custom2 = slug('hello-*-world', { custom: { '*': 'asterisk' } }); // hello-asterisk-world

slug(text, replacement)

Provided to support backwards-compatibility with the slug module.

const underscore = slug('i ♥ unicode', '_'); // i_love_unicode

Test .github/workflows/ci.yml

Run the unit tests with:

npm test

Contribute

Pull requests with mappings and tests for further scripts and languages are more than welcome.

Licence

Copyright 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020 Lovell Fuller and contributors.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100
No reviews found
Be the first to rate

Alternatives

No alternatives found

Tutorials

No tutorials found
Add a tutorial