glugify/config

Types

Config

Configuration options for customizing slugification behavior.

Each field controls a specific aspect of the slugification process:

separator: Character(s) used to separate words (default: “-”)
lowercase: Whether to convert to lowercase (default: True)
max_length: Optional maximum length limit (default: None)
word_boundary: Whether to truncate at word boundaries (default: False)
transliterate: Whether to convert Unicode to ASCII (default: True)
allow_unicode: Whether to allow Unicode characters in output (default: False)
custom_replacements: List of custom string replacements (default: [])
preserve_leading_underscore: Whether to keep leading underscores (default: False)
preserve_trailing_dash: Whether to keep trailing dashes (default: False)
stop_words: List of words to remove (default: [])
trim: Whether to trim whitespace (default: True)
locale: Locale for language-specific transliteration (default: locale.Default)
decamelize: Whether to split camelCase words (default: False)
decode_html_entities: Whether to decode HTML entities first (default: False)
ignore: Graphemes kept verbatim in the slug (default: [])

pub type Config {
  Config(
    separator: String,
    lowercase: Bool,
    max_length: option.Option(Int),
    word_boundary: Bool,
    transliterate: Bool,
    allow_unicode: Bool,
    custom_replacements: List(#(String, String)),
    preserve_leading_underscore: Bool,
    preserve_trailing_dash: Bool,
    stop_words: List(String),
    trim: Bool,
    locale: locale.Locale,
    decamelize: Bool,
    decode_html_entities: Bool,
    ignore: List(String),
  )
}

Constructors

Config(
  separator: String,
  lowercase: Bool,
  max_length: option.Option(Int),
  word_boundary: Bool,
  transliterate: Bool,
  allow_unicode: Bool,
  custom_replacements: List(#(String, String)),
  preserve_leading_underscore: Bool,
  preserve_trailing_dash: Bool,
  stop_words: List(String),
  trim: Bool,
  locale: locale.Locale,
  decamelize: Bool,
  decode_html_entities: Bool,
  ignore: List(String),
)

Values

default

</>

pub fn default() -> Config

Creates a default configuration with sensible defaults for most use cases.

Default values:

Separator: -
Lowercase: True
Max length: None (unlimited)
Word boundary: False
Transliterate: True
Allow unicode: False
Custom replacements: []
Preserve leading underscore: False
Preserve trailing dash: False
Stop words: []
Trim: True

Examples

let config = default()

seo_preset

</>

pub fn seo_preset() -> Config

Creates a configuration tuned for SEO-friendly URLs.

Same as default() but slugs are truncated to 60 characters at word boundaries, following search engine guidance on URL length.

Examples

let config = seo_preset()

validate_config

</>

pub fn validate_config(config: Config) -> Result(Config, String)

Validates configuration parameters and returns an error if invalid.

Currently validates:

Separator length must be <= 10 characters

Returns the same config if valid, or an error message if invalid.

with_allow_unicode

</>

pub fn with_allow_unicode(
  config: Config,
  allow_unicode: Bool,
) -> Config

Sets whether Unicode characters are allowed in the output.

When True, Unicode characters are preserved in the output. When False, only ASCII characters are allowed. Usually used with transliterate: False.

Examples

default()
|> with_transliterate(False)
|> with_allow_unicode(True)

with_custom_replacements

</>

pub fn with_custom_replacements(
  config: Config,
  replacements: List(#(String, String)),
) -> Config

Sets custom string replacements to apply before other processing.

Each tuple contains #(from, to) where from is replaced with to. Replacements are applied in the order provided.

Examples

default()
|> with_custom_replacements([
  #("&", " and "),
  #("@", " at "),
  #("%", " percent ")
])
// "Cats & Dogs @ 100%" -> "cats-and-dogs-at-100-percent"

with_decamelize

</>

pub fn with_decamelize(
  config: Config,
  decamelize: Bool,
) -> Config

Sets whether camelCase and PascalCase words are split before slugification.

Examples

default()
|> with_decamelize(True)
// "myAwesomeXMLParser" -> "my-awesome-xml-parser"

with_decode_html_entities

</>

pub fn with_decode_html_entities(
  config: Config,
  decode_html_entities: Bool,
) -> Config

Sets whether HTML entities (&, &, &) are decoded before slugification.

Useful when slugifying titles from CMS content or scraped HTML.

Examples

default()
|> with_decode_html_entities(True)
// "Tom &amp; Jerry" -> "tom-and-jerry"

with_ignore

</>

pub fn with_ignore(
  config: Config,
  ignore: List(String),
) -> Config

Sets graphemes that are kept verbatim in the slug: they are exempt from transliteration, are not converted to separators, and survive invalid-character removal.

Examples

default()
|> with_ignore(["#"])
// "C# rocks" -> "c#-rocks"

default()
|> with_ignore(["嗨"])
// "嗨 hello" -> "嗨-hello"

with_locale

</>

pub fn with_locale(
  config: Config,
  locale: locale.Locale,
) -> Config

Sets the locale used for language-specific transliteration rules.

Examples

import glugify/locale

default()
|> with_locale(locale.German)
// "Über München" -> "ueber-muenchen" (instead of "uber-munchen")

with_lowercase

</>

pub fn with_lowercase(config: Config, lowercase: Bool) -> Config

Sets whether the output should be converted to lowercase.

Examples

default()
|> with_lowercase(False)
// Results in: "Hello-World" instead of "hello-world"

with_max_length

</>

pub fn with_max_length(config: Config, max_length: Int) -> Config

Sets the maximum length for the generated slug.

If the value is negative, the config remains unchanged. Use with with_word_boundary(True) to truncate at word boundaries.

Examples

default()
|> with_max_length(10)
// Will truncate slugs to 10 characters maximum

with_preserve_leading_underscore

</>

pub fn with_preserve_leading_underscore(
  config: Config,
  preserve_leading_underscore: Bool,
) -> Config

Sets whether a leading underscore on the input is kept on the slug.

Useful when slugifying identifiers where a leading underscore is meaningful (private fields, hidden files).

Examples

default()
|> with_preserve_leading_underscore(True)
// "_private notes" -> "_private-notes"

with_preserve_trailing_dash

</>

pub fn with_preserve_trailing_dash(
  config: Config,
  preserve_trailing_dash: Bool,
) -> Config

Sets whether a trailing dash on the input is kept on the slug as a trailing separator.

Useful for slug fields that update live while the user is still typing, where “draft-” should not collapse to “draft”.

Examples

default()
|> with_preserve_trailing_dash(True)
// "draft-" -> "draft-"

with_separator

</>

pub fn with_separator(
  config: Config,
  separator: String,
) -> Config

Sets the separator character(s) used between words.

Examples

default()
|> with_separator("_")
// Results in: "hello_world" instead of "hello-world"

with_stop_words

</>

pub fn with_stop_words(
  config: Config,
  stop_words: List(String),
) -> Config

Sets a list of stop words to remove from the slug.

Stop words are removed after other processing but before final cleanup. Matching is case-insensitive.

Examples

default()
|> with_stop_words(["the", "a", "an", "and", "or"])
// "The Quick Brown Fox and the Lazy Dog" -> "quick-brown-fox-lazy-dog"

with_transliterate

</>

pub fn with_transliterate(
  config: Config,
  transliterate: Bool,
) -> Config

Sets whether Unicode characters should be transliterated to ASCII.

When True, characters like “café” become “cafe”. When False, Unicode characters are preserved or cause an error.

Examples

default()
|> with_transliterate(False)
|> with_allow_unicode(True)
// Preserves Unicode: "café" -> "café"

with_trim

</>

pub fn with_trim(config: Config, trim: Bool) -> Config

Sets whether to trim leading and trailing whitespace from the input.

This is applied early in the processing pipeline.

Examples

default()
|> with_trim(False)
// Preserves leading/trailing spaces in processing

with_word_boundary

</>

pub fn with_word_boundary(
  config: Config,
  word_boundary: Bool,
) -> Config

Sets whether truncation should respect word boundaries.

When True, truncation will not cut words in half. Only applies when max_length is set.

Examples

default()
|> with_max_length(10)
|> with_word_boundary(True)
// "hello world test" -> "hello" (not "hello worl")