ZID Name Utility

A lightweight utility for generating clean, lowercased, and hyphen-separated slugs from text. Specifically designed for creating Zettelkasten ID (ZID) note titles and filenames.

Table of Contents

• Description
• Features
• Installation
  • From Source
  • Standalone Executable
• Configuration
• Usage
• AutoHotkey Integration
• Development
• Kardenwort
• License

---

Description

zid-name is a focused tool that processes an input string or the current clipboard content. It extracts the first 4 words, replaces special characters (including German umlauts), and joins them with hyphens in lowercase. This ensures consistent and cross-platform friendly filenames and note titles.

Return to Top

Features

• Batch Mode Support: Process entire task lists or multiple titles in one go while preserving document structure.
• Smart Sanitization: Automatically detects whether to sanitize substrings (always) or multi-line blocks (based on config).
• ZID-Awareness: Standardized regex identifies 14-digit timestamps (ZIDs) with prefixes (bullets, checkboxes, numbers, and headings) and excludes ZIDs from word counts.
• Markdown Heading Support: Correctly handles # to ###### headers as structural prefixes.
• Sentence Boundary Handling: Automatically converts . to - to ensure clean slugs from multi-sentence titles.
• External Configuration: Customize the word limit, character replacements, and formatting via config.ini.
• Word Limiting: Automatically trims the result (excluding ZID) to the configured word count (default: 4).
• Umlaut Handling: Replaces ä, ö, ü, and ß with ae, oe, ue, and ss.
• Character Normalization: Replaces dots, underscores, and special punctuation with hyphens.
• Double Separator Cleanup: Automatically collapses multiple separators (e.g., -- -> -) for cleaner output.
• Extension Preservation: Configurable extension handling (preserve_extension_depth) to preserve file types like .mp4 or .tar.gz.
• Clipboard Integration: Seamlessly reads from and writes back to the system clipboard.

Return to Top

Installation

From Source

1. Clone the repository.
2. Install dependencies:

   pip install pyperclip

3. Run the script:

   python zid_name.py

Standalone Executable

You can find pre-built executables in the dist/ folder or under the Releases section.

Return to Top

Configuration

You can customize the script's behavior by modifying the config.ini file in the application directory.

[Settings]
slug_word_count = 4
process_non_zid_lines = false
# Preserves original extensions: e.g. 1 -> .pdf, 3 -> .1.de.srt. Takes priority over slugify.
preserve_extension_depth = 0
# Slugifies extensions: e.g. 1 -> -pdf, 3 -> -1-de-srt
slugify_extension_depth = 0
allowed_chars_regex = [^a-zA-Zа-яА-ЯёЁ0-9\s-]

[Format]
lowercase = true
separator = -

[Replacements]
ä = ae
ö = oe
ü = ue
ß = ss
_ = -
: = -
. = -

Settings

• slug_word_count: The maximum number of words to include in the generated slug (default: 4). This count excludes the 14-digit ZID and any preserved extensions (if configured).
• process_non_zid_lines: If true, lines without ZIDs in a batch will still be slugified. If false (default), only ZID lines are processed, preserving comments and headings.
• preserve_extension_depth: Number of extension parts to preserve verbatim (e.g. 1 for .pdf, 2 for .tar.gz). Set to 0 to disable preservation. Takes priority over slugify_extension_depth.
• slugify_extension_depth: Number of extension parts to preserve but convert to slug format (e.g. 1 turns .pdf into -pdf). Appended after the word count limit. Used only if preserve_extension_depth is 0.
• allowed_chars_regex: A regular expression defining which characters are kept before splitting into words.

Format

• lowercase: If true, the final output will be converted to lowercase.
• separator: The character used to join words (e.g., - or _).

Replacements

A list of specific character-to-string mappings. This is useful for handling umlauts or specific punctuation.

Return to Top

Usage

1. Copy the title or text you want to convert.
2. Execute the script using Python:

   python u:\voothi\20240929203511-zid-name\zid_name.py

   Note: You can also provide the string as a direct argument:

   python zid_name.py "My New Note Title"

3. Paste the generated ZID name into your destination.

The terminal will display the processed string for quick verification.

Return to Top

AutoHotkey Integration

For a more seamless workflow, you can use the zid-name.ahk script.

This script maps the process to Ctrl + Alt + ;, performing the following steps automatically:

1. Copies the currently selected text.
2. Processes it through the Python script.
3. Pastes the cleaned ZID name back into your active window.

Important

You must update the paths in the RunWait command within the .ahk script to match your local installation of Python and the location of zid_name.py.

Development

Verification Tests

A Python test suite is available in the tests/ directory to verify the logic for umlaut handling, ZID-awareness, and word counting.

To run the tests:

python -m unittest discover tests

Note: The tests rely on the current settings in config.ini. Ensure slug_word_count is set to 4 for the default test cases to pass.

Return to Top

Kardenwort Ecosystem

This project is part of the Kardenwort environment, designed to create a focused and efficient learning ecosystem.

Return to Top

License

MIT License. See LICENSE file for details.

Return to Top