Madomeda is a Python tool for managing markdown frontmatter in git repositories with rule-based normalization, template-driven generation, and optional LLM assistance.
## Project Structure
```
madomeda/
├── madomeda.py # Main entry point
├── requirements.txt # Python dependencies
├── .env # LLM configuration
├── README.md # Project documentation
├── USAGE.md # Usage examples
│
├── core/ # Core modules
│ ├── __init__.py
│ ├── database.py # SQLite database management
│ ├── repository.py # Git repository operations
│ ├── frontmatter.py # YAML frontmatter parsing
│ ├── rules.py # Rule engine
│ ├── template.py # Template management
│ ├── llm.py # LLM integration
│ ├── changelog.py # Changelog management
│ └── processor.py # Main processing logic
│
├── templates/ # Frontmatter templates
│ └── default.json # Default template
│
├── rules/ # Rule definitions
│ ├── tags_normalization.json
│ ├── tag_to_tags.json
│ └── lowercase_keys.json
│
├── prompts/ # LLM prompts
│ └── default.txt # Default system prompt
│
├── madomeda.db # SQLite database (gitignored)
└── madomeda_changelog.txt # Change log
```
## Key Features
### 1. Git Integration
- Tracks markdown files via git ls-files
- Extracts commit history (authors, dates, hashes)
- Ignores hidden files/folders (starting with '.')
- Respects --ignore-paths arguments
### 2. Database Management
- SQLite database (`madomeda.db`)
- Tables: files, frontmatter, commits, tags
- Tracks conformance status
- Stores all frontmatter versions
### 3. Rule Engine
Rules are JSON files in the `rules/` folder:
- **tags_normalization**: Converts tags to lowercase_with_underscores
- **tag_to_tags**: Renames 'tag' key to 'tags'
- **lowercase_keys**: All frontmatter keys must be lowercase
### 4. Template System
Templates define frontmatter structure with value strategies:
-`heur`: Use heuristics (git history, document analysis)
-`orig`: Use original frontmatter value
-`ai <prompt>`: Use LLM with specified prompt
Strategy priority: Options are tried left-to-right until one returns a value.
Example template:
```json
{
"title":"heur|orig",
"created":"heur|orig",
"changed":"heur|orig",
"authors":"heur|orig",
"version":"heur|orig",
"tags":"heur|orig|ai default"
}
```
### 5. LLM Integration
- OpenAI-compatible API support
- Structured output via JSON schema
- Configurable via .env file
- Fallback if API unavailable
### 6. Heuristic Values
-`title`: Extracted from # heading or filename
-`created`: First commit date (ISO 8601)
-`changed`: Latest commit date (ISO 8601)
-`authors`: List of all contributors
-`version`: Latest commit tag if exists, else short hash (7 chars)
