Slugify.Core 5.1.1

Slugify Core

This is a fork of the original project here: https://github.com/fcingolani/Slugify. This has been updated for .NET Standard 2.0 support (older versions support .NET Standard down to 1.3).

Simple Slug / Clean URL generator helper for Microsoft .NET.

With default settings, you will get an hyphenized, lowercase, alphanumeric version of any string you please, with any diacritics removed, whitespace and dashes collapsed, and whitespace trimmed.

For example, having:

a ambição cerra o coração

You'll get:

a-ambicao-cerra-o-coracao

Installation

You can get the Slugify NuGet package by running the following command in the Package Manager Console:

PM> Install-Package Slugify.Core

Or running dotnet add package Slugify.Core from the command line.

Upgrading from 4.x to 5.x

• 5.0 is significantly faster and uses less memory. 2-3x faster than version 4 and allocates about 20% less memory.
• DeniedCharactersRegex is no longer a string, and it now takes in a Regex object. This will allow you to use Source Generated regexes on platforms that support them. Using something like:

[GeneratedRegex(@"[^a-z0-9\-\._]")]
private static partial Regex GeneratedRegex();

• Using a generated regex version will be ever so slightly the fastest way of generating a slug on platforms that support it. However it will use a bit more memory.
• The way tab and new-line characters are handled has been changed. They are no longer translated to - by default and will instead be stripped. This will only be a noticeable change if you have disabled CollapseDashes (which is not the default).
• The option to disable collapsing whitespace has been removed.
• AllowedChars is renamed to AllowedCharacters.

Upgrading from 2.x to 3.x

• 3.0 is a significantly faster and less memory intensive version of the Slugifier. Whilst effort has been made to maintain backwards compatability, there may be some breaking changes.
• The SlugHelper.Config nested class has been renamed to just SlugHelperConfiguration.

Basic Usage

It's really simple! Just instantiate SlugHelper and call its GenerateSlug method with the string you want to convert; it'll return the slugified version:

using Slugify;

public class MyApp
{
    public static void Main()
    {
        SlugHelper helper = new SlugHelper();

        String title = "OLA ke ase!";

        String slug = helper.GenerateSlug(title);

        Console.WriteLine(slug); // "ola-ke-ase"
    }
}

Supporting Non-ASCII Characters

If you want to support non-ASCII characters, you can use the SlugHelperForNonAsciiLanguages class instead of SlugHelper. This is a derived class which will translate the characters provided into something "equivalent" in ASCII.

Configuration

The default configuration of SlugHelper will make the following changes to the passed input in order to generate a slug:

• Transform all characters to lower-case, to produce a lower-case slug.
• Trim all leading and trailing whitespace.
• Collapse all consecutive whitespace into a single space.
• Replace spaces with a dash.
• Remove all non-alphanumerical ASCII characters.
• Collapse all consecutive dashes into a single one.

You can customize most of this behavior by passing a SlugHelperConfiguration object to the SlugHelper constructor. For example, the following example will keep upper-case characters in the input and provides a custom handling for ampersands in the input:

// Creating a configuration object
var config = new SlugHelperConfiguration();

// Add individual replacement rules
config.StringReplacements.Add("&", "-");
config.StringReplacements.Add(",", "-");

// Keep the casing of the input string
config.ForceLowerCase = false;

// Create a helper instance with our new configuration
var helper = new SlugHelper(config);

var result = helper.GenerateSlug("Simple,short&quick Example");
Console.WriteLine(result); // Simple-short-quick-Example

The following options can be configured with the SlugHelperConfiguration:

ForceLowerCase

This specifies whether the output string should be converted to lower-case. If set to false, the original casing will be preserved. The lower-case conversion happens before any other character replacements are being made.

• Default value: true

TrimWhitespace

This specifies whether leading and trailing whitespace should be removed from the input string. The whitespace will be trimmed before any other character replacements are being made.

• Default value: true

CollapseDashes

This specifies wehther consecutive dashes ("-") should be collapsed into a single dash. This is useful to avoid scenarios like "foo & bar" becoming "foo--bar". Dashes will be collapsed after all other string replacements have been made before the final result string is returned.

• Default value: true

StringReplacements

This is a dictionary containing a mapping of characters that should be replaced individually before the translation happens. By default, this will replace space characters with a hyphen.

String replacements are being made after whitespace has been trimmed and collapsed, after the input string has been converted to lower-case characters, but before any characters are removed, to allow replacing characters that would otherwise be just removed.

• Default value:

  new Dictionary<string, string> {
     [" "] = "-", // replace space with a hyphen
  }
  

• Examples:

  var config = new SlugHelperConfiguration();
  
  // replace the dictionary completely
  config.StringReplacements = new() {
      ["ä"] = "ae",
      ["ö"] = "oe",
      ["ü"] = "ue",
  };
  
  // or add individual replacements to it
  config.StringReplacements.Add("ß", "ss");
  

AllowedCharacters

Set of characters that are allowed in the slug, which will be kept when the input string is being processed. By default, this contains all ASCII characters, the full stop, the dash and the underscore. This is the preferred way of controlling which characters should be replaced when generating the slug.

Characters that are not allowed will be replaced after string replacements are completed.

• Default value: Alphanumerical ASCII characters, the full stop (.), the dash (-), and the underscore (-). abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._)

• Examples:

  var config = new SlugHelperConfiguration();
  
  // add individual characters to the list of allowed characters
  config.AllowedCharacters.Add('!');
  
  // remove previously added or default characters
  config.AllowedCharacters.Remove('.');
  

DeniedCharactersRegex

Alternative method of specifying which characters will be allowed in the slug, which will replace the functionality of the AllowedChars set. The value must be a valid regular expression that specifies which characters are to be removed. Every match of this regular expression in the input string will be removed. The removal happens after string replacements are completed.

Specifying the DeniedCharactersRegex option will disable the character removal behavior from the AllowedChars option.

• Default value: null

• Examples:

  var helper = new SlugHelper(new SlugHelperConfiguration
  {
      // this is equivalent to the default behavior from `AllowChars`
      DeniedCharactersRegex = new(@"[^a-zA-Z0-9._-]")
  });
  Console.WriteLine(helper.GenerateSlug("OLA ke ase!")); // "ola-ke-ase"
  
  helper = new SlugHelper(new SlugHelperConfiguration
  {
      // remove certain characters explicitly
      DeniedCharactersRegex = new(@"[abcdef]")
  });
  Console.WriteLine(helper.GenerateSlug("abcdefghijk")); // "ghijk"
  
  helper = new SlugHelper(new SlugHelperConfiguration
  {
      // remove more complex matches
      DeniedCharactersRegex = new(@"foo|bar")
  });
  Console.WriteLine(helper.GenerateSlug("this is an foo example")); // "this-is-an-example"
  

MaximumLength

This will limit the length of the generated slug to be a maximum of the number of chars given by the parameter. If the truncation happens in a way that a trailing - is left, it will be removed.

• Default value: null