Slugify.Core 4.0.1

There is a newer prerelease version of this package available.
See the version list below for details.
dotnet add package Slugify.Core --version 4.0.1                
NuGet\Install-Package Slugify.Core -Version 4.0.1                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Slugify.Core" Version="4.0.1" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Slugify.Core --version 4.0.1                
#r "nuget: Slugify.Core, 4.0.1"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Slugify.Core as a Cake Addin
#addin nuget:?package=Slugify.Core&version=4.0.1

// Install Slugify.Core as a Cake Tool
#tool nuget:?package=Slugify.Core&version=4.0.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).

Build status Current NuGet release MIT license

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 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"
    }
}

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

CollapseWhiteSpace

This specifies whether consecutive whitespace should be replaced by just one space (" "). The whitespace will be collapsed 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");
    

AllowedChars

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.AllowedChars.Add('!');
    
    // remove previously added or default characters
    config.AllowedChars.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.

This functionality is kept in place for legacy compatibility reasons and since it relies on regular expressions, it will perform worse than using the AllowedChars way of specifying.

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 = "[^a-zA-Z0-9._-]"
    });
    Console.WriteLine(helper.GenerateSlug("OLA ke ase!")); // "ola-ke-ase"
    
    helper = new SlugHelper(new SlugHelperConfiguration
    {
        // remove certain characters explicitly
        DeniedCharactersRegex = @"[abcdef]"
    });
    Console.WriteLine(helper.GenerateSlug("abcdefghijk")); // "ghijk"
    
    helper = new SlugHelper(new SlugHelperConfiguration
    {
        // remove more complex matches
        DeniedCharactersRegex = @"foo|bar"
    });
    Console.WriteLine(helper.GenerateSlug("this is an foo example")); // "this-is-an-example"
    
Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (19)

Showing the top 5 NuGet packages that depend on Slugify.Core:

Package Downloads
Volo.CmsKit.Domain

Package Description

ZhileTime.CmsKit.Domain

Package Description

SpiderSharp

Web Crawling and Scraping Framework

Squidex.CLI.Core

Command Line Interface for Squidex Headless CMS

Dignite.Cms.Domain.Shared

Package Description

GitHub repositories (2)

Showing the top 2 popular GitHub repositories that depend on Slugify.Core:

Repository Stars
abpframework/abp
Open-source web application framework for ASP.NET Core! Offers an opinionated architecture to build enterprise software solutions with best practices on top of the .NET. Provides the fundamental infrastructure, cross-cutting-concern implementations, startup templates, application modules, UI themes, tooling and documentation.
madskristensen/MarkdownEditor2022
A Visual Studio extension
Version Downloads Last updated
5.0.0-prerelease.4 49,267 7/24/2023
4.0.1 857,291 2/22/2023
4.0.0 2,502 2/22/2023
3.0.0 1,258,747 11/26/2020
2.3.0 935,037 8/7/2018
2.2.2 10,479 6/27/2018
2.2.1 12,996 3/15/2018
2.2.0 66,830 3/8/2017
2.1.0 48,623 9/14/2016

4.0.0 - Bug fix relase from 3.0.0
3.0.0 - Much improved performance and memory usage. Config file renamed. Potentially some breaking changes but none we're aware of
2.4.0 - NetStandard 2.0 support only
2.3.0 - ISlugHelper interface added. Thanks @jcharlesworthuk
2.2.2 - NetStandard 2.0
2.2.1 - NuGet package updates
2.2.0 - Minor tweaks