# README Starter — Slugsmith, a Tiny Python CLI

## Document Directory

This paste contains 4 documents:

- [README.md](https://marke.st/p/01M33QGSYRXED9CZS06KXDE622/README.md) ← (current)
- [slugsmith.py](https://marke.st/p/01M33QGSYRXED9CZS06KXDE622/slugsmith.py) (code)
- [test_slugsmith.py](https://marke.st/p/01M33QGSYRXED9CZS06KXDE622/test_slugsmith.py) (code)
- [CHANGELOG.md](https://marke.st/p/01M33QGSYRXED9CZS06KXDE622/CHANGELOG.md)

---

## README.md

# Slugsmith

### Small words. Clean URLs. No dependencies.

**PYTHON 3.10+ · STANDARD LIBRARY ONLY · RUNNABLE SAMPLE**

> An original demonstration project for Marke.st. Slugsmith is a tiny example utility, not an established package or a claim about a real business.

Turn a title into a predictable ASCII slug. This collection includes the implementation, tests, and a changelog—not just a screenshot of code.

```text
"A Better Project Handoff!"  →  a-better-project-handoff
"Crème brûlée & coffee"     →  creme-brulee-coffee
"!!!"                      →  untitled
```

## Quick start

Save `slugsmith.py` and `test_slugsmith.py` from this collection into the same directory. No package installation or account is required.

```bash
python3 slugsmith.py "A Better Project Handoff!"
python3 slugsmith.py --max-length 24 "Make documentation easy to share"
python3 -m unittest -v test_slugsmith.py
```

The CLI reads the text argument and prints one slug. It makes no network requests and writes no files.

**Sample verification:** the included function and ten unit-test methods were executed in a local Python environment when this collection was prepared; all ten passed. The CLI example `Hello, world!` returned `hello-world`. This is a test of the sample, not a guarantee for every downstream use.

## As a library

```python
from slugsmith import slugify

assert slugify("Crème brûlée & coffee") == "creme-brulee-coffee"
assert slugify("Hello, world!", max_length=8) == "hello-wo"
```

## Behavior you can depend on in this sample

| Input condition | Behavior |
|---|---|
| Whitespace or punctuation | Converted to a single separator between words |
| Accented Latin text | Normalized, then reduced to ASCII where possible |
| Non-ASCII characters without an ASCII decomposition | Removed, not linguistically transliterated |
| Empty result | Falls back to `untitled` |
| Length limit | Truncates to the limit, then strips a trailing hyphen |
| Invalid limit | Raises a clear error |

**Not a uniqueness system.** Two different titles can produce the same slug. Add your own identifier or collision-handling policy when using slugs as database keys. This utility is not a filesystem path sanitizer or a security boundary.

## Project map

```text
README.md             You are here
slugsmith.py          CLI and pure function
test_slugsmith.py     Executable unit tests
CHANGELOG.md          Example release notes
```

## A README checklist worth stealing

- [x] Explain the outcome before the implementation.
- [x] Show a short, copyable first command.
- [x] Include sample input and output.
- [x] Document edge cases and limitations.
- [x] Put real code beside the documentation.

---
*An original code example published with [Marke.st](https://marke.st). A README, source files, and tests—one shareable collection.*