madomeda/ADD_ONLY_EXAMPLES.md

Add-Only Mode Examples

Overview

The --add-only flag preserves existing frontmatter keys while adding missing template fields.

Example 1: Preserving Custom Fields

Input File

---
Summary: A comprehensive guide to neural networks
CustomField1: Important value
CustomField2: Another important value
Status: published
---

# Neural Networks Guide
...

Regular Mode (Default)

python madomeda.py

Result:

---
title: Neural Networks Guide
created: '2025-10-23T18:06:22+02:00'
changed: '2025-10-23T18:06:22+02:00'
authors:
- Test User
version: 44ed278
tags: []
---

⚠️ Warning issued: "Metadata will be discarded: Summary, CustomField1, CustomField2, Status"

Add-Only Mode

python madomeda.py --add-only

Result:

---
customfield1: Important value
customfield2: Another important value
status: published
description: This is a comprehensive guide to neural networks
title: Neural Networks Guide
created: '2025-10-23T18:06:22+02:00'
changed: '2025-10-23T18:06:22+02:00'
authors:
- Test User
version: 44ed278
tags: []
---

✅ No warnings - all fields preserved (after normalization)

Example 2: Field Renaming Rules

Rules are still applied in add-only mode:

Input

---
Title: My Document
Tag: Python, AI
Summary: Introduction to Python
CustomKey: custom value
---

Add-Only Result

---
title: My Document              # Title → title (lowercase)
customkey: custom value         # CustomKey → customkey (lowercase)
description: Introduction to Python  # Summary → description (rule)
created: '2025-10-23T17:27:16+02:00'
changed: '2025-10-23T17:27:16+02:00'
authors:
- John Doe
version: 34d2d05
tags:                           # Tag → tags (rule)
- python                        # Python → python (normalized)
- ai                            # AI → ai (normalized)
---

Rules Applied in Add-Only Mode

1. Lowercase keys: All keys converted to lowercase
2. tag → tags: Singular renamed to plural
3. summary → description: Field rename
4. Tag normalization: lowercase_with_underscores

When to Use Each Mode

Use Regular Mode When:

• Enforcing strict template compliance
• Starting fresh with standardized metadata
• You want only template-defined fields

Use Add-Only Mode When:

• Enriching existing documentation
• Preserving custom workflow fields
• Migrating from another system
• You have valuable metadata not in the template

Combining with Other Options

Add-Only + WhatIf

Preview what will be added without making changes:

python madomeda.py --add-only --whatif

Add-Only + No-Confirm

Process without confirmation prompts:

python madomeda.py --add-only --no-confirm

Add-Only + Ignore-Paths

Preserve custom fields but skip certain directories:

python madomeda.py --add-only --ignore-paths archive drafts

Field Ordering

In add-only mode, the final frontmatter contains:

1. Normalized original fields (custom keys)
2. Template fields (if not already present)

Order may vary as YAML dictionaries don't guarantee order.