sus: Static URL Shortener

sus is a static site based URL shortener. Simple idea: generate a static site with a bunch of redirect-slug-goes-here/index.html files with nothing but an HTML redirect in them.

Installation

# note: you’ll need Python 3.9 or higher
pip install sus

Usage

1. Install package
2. Have an input file ready
3. Have a home.html file ready (optional)
4. Run sus in the same directory as input
5. Voilà—your results are in the output/ directory

Input

sus expects to find a file named input in the current directory, and each row consists of the redirect slug and destination URL, separated by a pipe (|). Lines starting with the hash # are considered comments and thus ignored, and blank lines are ignored as well.

E.g.,

nk | https://nkantar.com
sus | https://github.com/nkantar/sus

# this is a comment and will be ignored
# the blank line above will also be ignored

If one were to serve output/ on https://sus-example.nkantar.com, then https://sus-example.nkantar.com/nk would redirect to https://nkantar.com and https://sus-example.nkantar.com/sus would redirect to https://github.com/nkantar/sus.

That example site exists, and its repository can be found at https://github.com/nkantar/sus-example.nkantar.com.

Homepage

If sus finds a home.html file next to input, it will copy it to output/index.html, thereby generating a homepage. If it doesn’t, it will simply carry on.

Pronunciation

Much controversy has sparked around the pronunciation of the project’s name (no, it hasn’t). As such, here is the definitive guide on doing so, as conceived by the original author. Please note that—much like with GIF —others may have different ideas, and who’s to say the author knows what he’s talking about anyway?

“sus” is in this case pronounced as in “suspicious”, and Wiktionary helpfully provides the following guide:

• IPA (key): /sʌs/
• Rhymes: -ʌs
• Homophone: suss

Development

The project uses uv, just, and modd. Running uv sync should get you set up for local development, uv run just -l should show you some optional commands, and uv run modd is probably most useful while making changes.

The main branch is the bleeding edge version. Git tags correspond to releases.

Contributing Guidelines

Contributions of all sorts are welcome, be they bug reports, patches, or even just feedback. Creating a new issue or pull request is probably the best way to get started.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

License

This project is licensed under the MIT license. See LICENSE file for details.