madomeda/GETTING_STARTED.md

title, created, status, priority, published, tags, reviewers

title	created	status	priority	published	tags	reviewers
Getting Started with Madomeda	2025-10-23T18:33:48+02:00	draft	5	false

Getting Started with Madomeda

Prerequisites

• Python 3.7+
• Git repository with markdown files
• (Optional) OpenAI-compatible API for LLM features

Installation

1. Clone or download the Madomeda repository

2. Install dependencies:

   pip install -r requirements.txt
   

3. (Optional) Configure LLM: Edit .env file:

   OPENAI_API_URL=https://api.openai.com/v1
   OPENAI_MODEL=gpt-4
   OPENAI_API_KEY=your-actual-api-key
   

Your First Run

1. Navigate to your markdown repository:

   cd /path/to/your/markdown/repo
   

2. Run in dry-run mode to see what would change:

   python /path/to/madomeda/madomeda.py --whatif
   

3. Review the output - it will show:

   • Files discovered
   • Existing frontmatter (if any)
   • Proposed changes
   • Warnings about discarded metadata

4. Run for real if you're happy with the changes:

   python /path/to/madomeda/madomeda.py
   

5. Check the results:

   • Open modified markdown files
   • Review madomeda_changelog.txt
   • Inspect database: python /path/to/madomeda/inspect_db.py madomeda.db

Understanding the Output

Already Conformant

Processing: example.md
  Found existing frontmatter
  OK Already conformant

Meaning: File has correct frontmatter, no changes needed.

Will Update

Processing: example.md
  Found existing frontmatter
  WARNING Metadata will be discarded: CustomField
  Would update frontmatter:
    Changes: +created, +authors, -CustomField

Meaning: File will be updated. Custom fields not in template will be removed.

No Frontmatter

Processing: example.md
  No frontmatter found
  Would update frontmatter:
    Changes: +title, +created, +changed, +authors, +version, +tags

Meaning: New frontmatter will be added.

Common Workflows

Preview Changes

python madomeda.py --whatif

Process Specific Directory

python madomeda.py --dir ~/Documents/wiki

Skip Confirmations

python madomeda.py --no-confirm

Ignore Certain Paths

python madomeda.py --ignore-paths archive drafts templates

Force Regeneration

python madomeda.py --force

Use Custom Template

python madomeda.py --template minimal

(First create templates/minimal.json)

Customization

Create Custom Template

1. Create templates/mytemplate.json:

   {
     "title": "heur|orig",
     "date": "heur|orig",
     "tags": "orig|ai default",
     "author": "heur|orig"
   }
   

2. Use it:

   python madomeda.py --template mytemplate
   

Add Custom Rule

See RULES_GUIDE.md for comprehensive rule writing documentation.

1. Create ~/.config/madomeda/rules/60_my_rule.json:

   {
     "name": "my_custom_rule",
     "description": "Description of what this rule does",
     "field": "my_field",
     "priority": 60,
     "action": "normalize_value",
     "pattern": "[^a-z]",
     "replacement": "",
     "llm_prompt": "Instructions for LLM"
   }
   

2. Rules are automatically loaded - no code changes needed!

Customize LLM Prompt

1. Create prompts/custom.txt:

   You are a documentation expert. Analyze the content and suggest metadata...
   

2. Reference in template:

   {
     "summary": "ai custom"
   }
   

Troubleshooting

"Not a git repository"

Solution: Ensure you're in a directory with .git/ folder or use --dir to specify one.

"Module not found"

Solution: Run pip install -r requirements.txt

"LLM error: 401"

Solution:

• Update .env with valid API key
• Or ensure template doesn't require ai strategy
• The tool works fine without LLM using heur and orig strategies

"Metadata will be discarded"

Solution:

• Review the warning
• Add fields to template if you want to keep them
• Use --no-confirm to auto-accept
• Press 'n' to skip that file

Database locked

Solution: Close any programs accessing madomeda.db

Best Practices

1. Always test first: Use --whatif before making changes
2. Commit before processing: Ensure you can revert if needed
3. Review warnings: Check what metadata will be lost
4. Customize templates: Match your needs, not defaults
5. Version control: Commit the database to track history
6. Regular runs: Process new files as they're added

Files Generated

• madomeda.db - SQLite database (gitignored by default)
• madomeda_changelog.txt - Change log
• templates/ - Created if missing
• rules/ - Created if missing
• prompts/ - Created if missing

Getting Help

1. Check documentation:

   • README.md - Overview
   • USAGE.md - Detailed examples
   • RULES_GUIDE.md - Writing custom rules
   • LITERAL_VALUES.md - Template literal values
   • CONFIGURATION.md - Configuration options
   • STRUCTURE.md - Architecture
   • IMPLEMENTATION.md - Technical details

2. Inspect database:

   python inspect_db.py
   

3. Review changelog:

   cat madomeda_changelog.txt
   

Example Session

# Navigate to your repo
cd ~/my-knowledge-base

# First run (dry run)
python ~/tools/madomeda/madomeda.py --whatif

# Output shows what will change
# Review and decide

# Run for real
python ~/tools/madomeda/madomeda.py

# Check results
cat madomeda_changelog.txt
git diff

# Commit changes
git add .
git commit -m "Normalize frontmatter with Madomeda"

Tips

• Start with --whatif always
• Use --no-confirm for batch processing
• Keep madomeda.db to track history
• Review madomeda_changelog.txt after runs
• Create templates for different doc types
• Tags are automatically collected and normalized

Success!

If you see:

Processing complete!
Total unique tags in repository: X

You're done! Your frontmatter has been normalized and tracked.