tagitmd 0.1.0

CLI tool to add tags to markdown frontmatter

tagitmd

CLI tool to add tags to markdown frontmatter.

What it does

tagitmd scans markdown files in a directory and adds tags to their YAML frontmatter. It intelligently handles existing frontmatter, creating it if needed, and can optionally skip files that already have tags. You can also specify the path and disable recursion.

Installation

pip install -e .

Usage

tagitmd TAG [TAG...] [OPTIONS]

Examples

# Add tags to all markdown files in current directory
tagitmd python tutorial

# Add tags to files in a specific directory
tagitmd python --path /path/to/notes

# Preview changes without modifying files
tagitmd python tutorial --dry-run

# Only add tags to files that don't have any tags yet
tagitmd python --only-untagged

# Process only the target directory (not subdirectories)
tagitmd python --no-recursive

Flags

--path, -p

• Type: Directory path
• Default: Current directory (.)
• Description: Directory to process for markdown files

--dry-run

• Type: Flag
• Default: False
• Description: Preview changes without modifying any files. Shows what would be changed.

--only-untagged

• Type: Flag
• Default: False
• Description: Only modify files that don't have any existing tags in their frontmatter

--recursive / --no-recursive

• Type: Boolean flag
• Default: True (recursive)
• Description: Whether to search subdirectories recursively

Development Guide

Setup

Run the setup script to create a virtual environment and install dependencies:

bash setup-dev.sh

Or use Make:

make setup-dev

Manual Setup

If you prefer to set up manually:

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate

# Install package in development mode
pip install -e .

# Install development dependencies
pip install -r requirements.txt

Available Make Commands

make help         # Show available commands
make setup-dev    # Run setup-dev.sh script
make install-dev  # Install package with dev dependencies
make test         # Run tests with coverage
make build        # Build distribution packages
make lint         # Run code quality checks
make clean        # Clean build artifacts and venv

Running Tests

make test

Or directly with pytest:

pytest tests/ -v --cov=tagitmd --cov-report=term-missing

Building Distribution

make build

This will create distribution packages in the dist/ directory.

Publishing to PyPI

Prerequisites

1. Register accounts:

   • Test PyPI: https://test.pypi.org/account/register/
   • Production PyPI: https://pypi.org/account/register/

2. Create API tokens:

   • Test PyPI: https://test.pypi.org/manage/account/#api-tokens
   • Production PyPI: https://pypi.org/manage/account/#api-tokens
   • Set scope to "Entire account" for first upload

3. Configure credentials: Copy .pypirc.example to ~/.pypirc and add your API tokens:

   cp .pypirc.example ~/.pypirc
   chmod 600 ~/.pypirc
   

   Edit ~/.pypirc and replace the placeholder tokens with your actual tokens.

Publishing Steps

Test on Test PyPI (Recommended First)

make publish-test

Then test installation:

pip install --index-url https://test.pypi.org/simple/ --no-deps tagitmd

Publish to Production PyPI

make publish

This will:

1. Clean previous builds
2. Build source and wheel distributions
3. Check distribution files for errors
4. Prompt for confirmation before uploading
5. Upload to PyPI

Manual Publishing (Alternative)

If you prefer manual control:

# Build
python3 -m build

# Check distributions
python3 -m twine check dist/*

# Upload to Test PyPI
python3 -m twine upload --repository testpypi dist/*

# Upload to PyPI
python3 -m twine upload dist/*

Version Management

Update version in both files before publishing:

• pyproject.toml (line 7)
• tagitmd/__init__.py (line 3)

Requirements

• Python 3.8 or higher
• click >= 8.0
• python-frontmatter >= 1.0.0

License

MIT