DOCSEARCHbyAlgolia
Submit Docs

SpeakingURL

repository·master·Indexed 22 days ago

https://github.com/pid/speakingurl

A library for generating SEO-friendly, semantic, or 'pretty' URLs (slugs) from strings via transliteration. Version 14.0.1 supports multiple languages using ISO 639-1 codes and provides customizable options for separators, character sets, casing, and truncation through the getSlug() and createSlug() functions.

Tokens
1.5K
Snippets
5
Records
6
Agent score
28%

What's inside speakingurl

  1. Install SpeakingURL

    master

    You can install SpeakingURL using various package managers depending on your environment:

    Node.js (npm):

    npm install speakingurl --save

    Node.js (yarn):

    yarn add speakingurl --dev

    Bower:

    bower install --save speakingurl

    Component:

    component install pid/speakingurl

    Ruby on Rails: Add the following to your Gemfile:

    gem 'speakingurl-rails'
    npm install speakingurl --save

  2. Integrate SpeakingURL with Ruby on Rails

    master
    SpeakingURL provides a Railtie to automatically integrate with Ruby on Rails applications. When the speakingurl-rails gem is included in a Rails project, it uses an initializer to prepend the SpeakingURL asset paths to the Sprockets environment. This ensures that any assets provided by the gem are correctly discovered by the Rails asset pipeline.

  3. Create a custom slug function with createSlug()

    master

    If you need to reuse a specific configuration multiple times, use createSlug(options) to generate a pre-configured function.

    Parameters:

    • options (object|string): The configuration object or separator string used to initialize the new function.

    Example:

    var speakingurl = require('speakingurl');

var options = {
    maintainCase: true,
    separator: '_'
};

var mySlug = speakingurl.createSlug(options);
var slug = mySlug("Schöner Titel läßt grüßen!? Bel été !");
// Output: Schoener_Titel_laesst_gruessen_Bel_ete
    var mySlug = require('speakingurl').createSlug({
    maintainCase: true,
    separator: '_'
});

var slug = mySlug("Schöner Titel läßt grüßen!? Bel été !");
// Output: Schoener_Titel_laesst_gruessen_Bel_ete

  4. Use getSlug() to generate a slug

    master

    The getSlug(input, [options]) function converts a string into a transliterated, SEO-friendly slug.

    Parameters:

    • input (string): The string you want to convert.
    • options (object|string): A configuration object or a simple separator string.

    Common Configuration Options:

    • separator (string, default: '-'): The character used to replace whitespaces.
    • lang (string|boolean, default: 'en'): ISO 639-1 code for language-specific transliteration (e.g., 'de', 'fr', 'es', 'tr'). Setting to false disables language-specific transliteration.
    • symbols (boolean, default: true): If false, symbols are not converted.
    • maintainCase (boolean, default: false): If true, maintains the original case of characters.
    • titleCase (boolean|array, default: false): If true, converts to title-case. If an array is provided, those specific words are omitted from title-casing.
    • truncate (number, default: 0): The maximum length of the slug. If > 0, it trims the length without breaking words.
    • uric (boolean, default: false): If true, allows characters: ;, ?, :, @, &, =, +, $, ,, /.
    • uricNoSlash (boolean, default: false): If true, allows the same as uric but excludes /.
    • mark (boolean, default: false): If true, allows characters: -, _, ., !, ~, *, ', (, ).
    • custom (object|array, default: {}):
      • An object provides a custom map for translation (overwrites all others).
      • An array adds specific characters to the allowed charMap.
    var getSlug = require('speakingurl');

// Basic usage
var slug = getSlug("Schöner Titel läßt grüßen!? Bel été !");
// Output: schoener-titel-laesst-gruessen-bel-ete

// Using a custom separator
var slug = getSlug("Schöner Titel läßt grüßen!? Bel été !", '*');
// Output: schoener*titel*laesst*gruessen*bel*ete

// Using a config object
var slug = getSlug("Schöner Titel läßt grüßen!? Bel été !", {
    separator: '_'
});
// Output: schoener_titel_laesst_gruessen_bel_ete

  5. Reference: getSlug configuration options

    master

    The following options are available for getSlug(input, options) and createSlug(options):

    OptionTypeDefaultDescription
    separatorstring'-'Character that replaces whitespaces
    langstring/boolean'en'ISO 639-1 code for language-specific transliteration
    symbolsbooleantrueWhether to convert symbols according to lang
    maintainCasebooleanfalseWhether to maintain character case
    titleCaseboolean/arrayfalseConvert to title-case; if array, omit those words
    truncatenumber0Max length (trims without breaking words)
    uricbooleanfalseAllow ;, ?, :, @, &, =, +, $, ,, /
    uricNoSlashbooleanfalseAllow ;, ?, :, @, &, =, +, $, ,
    markbooleanfalseAllow -, _, ., !, ~, *, ', (, )
    customobject/array{}Object for custom translation map or array for allowed chars
    {
  "separator": "-",
  "lang": "en",
  "symbols": true,
  "maintainCase": false,
  "titleCase": false,
  "truncate": 0,
  "uric": false,
  "uricNoSlash": false,
  "mark": false,
  "custom": {}
}

  6. Import SpeakingURL

    master

    To use SpeakingURL in your JavaScript project, require the module. The main entrypoint exports the core slug generation functionality, including getSlug and createSlug methods.

    const speakingurl = require('speakingurl');