Remove test file

2025-10-23 18:33:48 +02:00
parent 0463d73ef9
commit 8c4f612e4b
33 changed files with 2718 additions and 25 deletions
@@ -0,0 +1,143 @@
+# 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
+```yaml
+---
+Summary: A comprehensive guide to neural networks
+CustomField1: Important value
+CustomField2: Another important value
+Status: published
+---
+
+# Neural Networks Guide
+...
+```
+
+### Regular Mode (Default)
+```bash
+python madomeda.py
+```
+
+**Result:**
+```yaml
+---
+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
+```bash
+python madomeda.py --add-only
+```
+
+**Result:**
+```yaml
+---
+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
+```yaml
+---
+Title: My Document
+Tag: Python, AI
+Summary: Introduction to Python
+CustomKey: custom value
+---
+```
+
+### Add-Only Result
+```yaml
+---
+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:
+```bash
+python madomeda.py --add-only --whatif
+```
+
+### Add-Only + No-Confirm
+Process without confirmation prompts:
+```bash
+python madomeda.py --add-only --no-confirm
+```
+
+### Add-Only + Ignore-Paths
+Preserve custom fields but skip certain directories:
+```bash
+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.