Slugify
DevelopmentslugifySlugify is an Agent Skill for development published in the persian-tools/persian-tools repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Generate URL-safe slugs from Persian text, with options for separator, lowercase, max length, custom replacements, and Persian digit handling. Use when building URL paths from article titles, file names from user-typed strings, or anchor IDs. Triggers on mentions of slugify, createSlug, URL-safe Persian, slug from Farsi, prettify URL.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/persian-tools/persian-tools/blob/HEAD/skills/slugify/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/slugify, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
slugify — URL-safe slugs from Persian text
import {
slugify,
createSlug,
slugifyWithNumbers,
slugifySimple,
} from "@persian-tools/persian-tools";
// CommonJS
const {
slugify,
createSlug,
slugifyWithNumbers,
slugifySimple,
} = require("@persian-tools/persian-tools");
Public exports
slugify(text: string, options?: SlugifyOptions): string
createSlug(text: string, separator?: string): string
slugifyWithNumbers(text: string, separator?: string): string
slugifySimple(text: string): string
interface SlugifyOptions {
separator?: string; // default "-"
lowercase?: boolean; // default true (lowercases Latin only — Persian has no case)
removeRepeatedSeparators?: boolean; // collapse "--" → "-", default true
maxLength?: number; // truncate after slug build
preserveNumbers?: boolean; // default true — Persian digits kept; English digits stay as-is
customReplacements?: Record<string, string>;
}
Basic usage
import { slugify } from "@persian-tools/persian-tools";
slugify("سلام دنیا"); // "سلام-دنیا"
slugify("چگونه برنامهنویسی یاد بگیریم؟"); // "چگونه-برنامه-نویسی-یاد-بگیریم"
slugify("Hello سلام 2024"); // "hello-سلام-2024"
With options
slugify("سلام دنیا", { separator: "_" }); // "سلام_دنیا"
slugify("سلام دنیا", { maxLength: 8 }); // "سلام-دن"
slugify("سلام دنیا", { lowercase: false }); // doesn't lowercase Latin
slugify("سال ۱۴۰۰", { preserveNumbers: true }); // "سال-۱۴۰۰" (Persian digits preserved)
Convenience exports
createSlug(text, separator?)—slugifywith the sameseparatordefault-overridable.slugifyWithNumbers(text, separator?)— slugify keeping digits intact.slugifySimple(text)— barebones slugification (no options).
These are thin wrappers; you can always call slugify(text, ...) directly.
What it does internally
- Validates input is a non-empty string. Otherwise throws (likely
Error, notTypeError— seesrc/modules/slugify/index.ts:65). - Normalises Arabic characters → Persian via
toPersianChars. - Applies
SLUG_REPLACEMENTS(e.g.آ → ا,ة → ه, drops Arabic diacritics). - Applies
PUNCTUATION_REPLACEMENTS(strips؟ ، « »etc.; converts Arabic-Indic digits to English). - Applies any
customReplacements. - Replaces whitespace runs with
separator, optionally collapses repeated separators, optionally truncates tomaxLength.
Common pitfalls
- Throws on empty string. Pre-check
text.trim().length > 0. lowercase: trueaffects only Latin characters; Persian doesn't have case.preserveNumbers: truekeeps Persian digits, which may NOT be URL-safe in some contexts (browsers handle them fine, but some servers reject non-ASCII paths). For pure-ASCII URLs, setpreserveNumbers: falseand pre-convert digits withdigitsFaToEn.maxLengthtruncates after slug building — the final slug may end on a separator if you're unlucky. Trim trailing separators yourself if it matters.- Custom replacements run after defaults — they can override punctuation handling. Useful for vocabulary-specific tweaks (e.g. brand-name expansions).
References
- Tests:
test/slugify.spec.ts - Related:
URLfixskill (decode percent-encoded URLs before slugifying)