madomeda/LITERAL_VALUES.md

Template Strategy: Literal Values

Overview

Templates support static/literal values using the lit: prefix. This allows you to specify fallback values when other strategies don't produce results.

Syntax

{
  "field": "strategy1|strategy2|lit:static value"
}

Strategy Types

1. heur - Use heuristics (git history, document analysis)
2. orig - Use original frontmatter value
3. ai - Use LLM inference
4. lit:value - Use literal/static value

Execution Order

Strategies are tried left to right until one returns a non-null value.

Examples

Example 1: Author Fallback

If git history has no authors, use a default:

{
  "authors": "heur|orig|lit:Ole Valente <ole@covalente.dk>"
}

Behavior:

• Try heuristics (git authors)
• If empty, try original frontmatter
• If still empty, use "Ole Valente ole@covalente.dk"

Example 2: Status Field

Always set a status field to "draft":

{
  "status": "lit:draft"
}

Behavior:

• Immediately use "draft" (no other strategies)

Example 3: Version with Fallback

{
  "version": "heur|orig|lit:0.1.0"
}

Behavior:

• Try git tag/hash
• If no git, try original
• If still nothing, use "0.1.0"

Example 4: Category

{
  "category": "orig|lit:uncategorized"
}

Behavior:

• Use original category if exists
• Otherwise mark as "uncategorized"

Example 5: Complete Template with Fallbacks

{
  "title": "heur|orig|lit:Untitled Document",
  "created": "heur|orig",
  "changed": "heur|orig",
  "authors": "heur|orig|lit:Unknown Author",
  "version": "heur|orig|lit:0.1.0",
  "tags": "heur|orig|ai default",
  "status": "lit:draft",
  "category": "orig|lit:general"
}

List Values

For list fields (like tags), use JSON array notation:

{
  "tags": "heur|orig|lit:[]"
}

This creates an empty list if no tags are found.

Or with default tags:

{
  "keywords": "orig|lit:[\"general\", \"misc\"]"
}

Note: List values in lit: are parsed as strings, so complex structures should be avoided. For lists, prefer empty [] or use AI inference.

Common Patterns

Pattern 1: Required Field with Default

{
  "author": "orig|lit:Anonymous"
}

Pattern 2: Preserve Original or Set Default

{
  "priority": "orig|lit:medium"
}

Pattern 3: Try Everything, Then Default

{
  "summary": "orig|ai default|lit:No description available"
}

Pattern 4: Static Value (No Fallback Needed)

{
  "type": "lit:document",
  "format": "lit:markdown"
}

Use Cases

1. Personal Knowledge Base

Set yourself as default author:

{
  "authors": "heur|lit:Jane Doe <jane@example.com>"
}

2. Organization Defaults

{
  "organization": "lit:Acme Corp",
  "license": "lit:MIT",
  "confidential": "lit:false"
}

3. Workflow States

{
  "status": "orig|lit:draft",
  "reviewed": "orig|lit:false",
  "published": "orig|lit:false"
}

4. Document Classification

{
  "type": "lit:article",
  "category": "orig|ai default|lit:uncategorized",
  "audience": "orig|lit:internal"
}

Special Considerations

Empty Strings

{
  "note": "lit:"
}

This sets the field to an empty string.

Spaces in Values

Spaces are preserved:

{
  "title": "lit:My Document Title"
}

Results in: title: "My Document Title"

Multiple Words

No quotes needed in template:

{
  "author": "lit:John Smith"
}

Email Addresses

Special characters work fine:

{
  "contact": "lit:admin@example.com"
}

Lists (Advanced)

For simple lists, you can use:

{
  "reviewers": "lit:[]"
}

But for populated lists, prefer AI or heuristics as literal list parsing is string-based.

Testing Your Template

Test with --whatif

madomeda --template my-template --whatif

Check a specific file

# Process just one file
madomeda --template my-template | grep -A 10 "Processing: myfile.md"

Troubleshooting

Literal Value Not Applied

Issue: Field is empty even with lit:value

Cause: Another strategy succeeded earlier in the chain

Solution: Move lit: to the beginning if you want it to always apply:

{
  "status": "lit:draft"  // Always use draft
}

Wrong Value Type

Issue: List field gets string instead of array

Cause: lit: with complex JSON isn't parsed

Solution: Use lit:[] for empty lists, or use AI/heuristics for populated lists

Complete Example Template

File: ~/.config/madomeda/templates/blog-post.json

{
  "title": "heur|orig|lit:Untitled Post",
  "date": "heur|orig",
  "author": "heur|orig|lit:Blog Team",
  "category": "orig|lit:general",
  "tags": "orig|ai default",
  "status": "lit:draft",
  "published": "orig|lit:false",
  "featured": "orig|lit:false",
  "excerpt": "orig|ai excerpt"
}

Usage:

madomeda --template blog-post

Result for new file:

---
title: My Blog Post  # From # heading
date: '2025-10-23T19:30:00+02:00'  # From git
author: Blog Team  # Literal fallback (no git author found)
category: general  # Literal (no original)
tags:  # From AI
- blogging
- tutorials
status: draft  # Literal
published: false  # Literal
featured: false  # Literal
excerpt: A comprehensive guide...  # From AI
---

Best Practices

1. Always provide fallbacks for critical fields
2. Use heur first to leverage git metadata
3. Use orig second to preserve existing values
4. Use lit last as safety net
5. Keep literals simple - avoid complex structures
6. Document your templates in comments (though JSON doesn't support them, keep external docs)

See Also

• CONFIGURATION.md - Template configuration
• USAGE.md - Template usage examples
• STRUCTURE.md - Template system architecture