Machine Readable Content

Machine-Readable Content

The Problem

Emoji, color codes, and visual markers in files parsed by regex or LLMs break tooling:

<!-- Breaks JSON extraction -->
| Status | Count |
|--------|-------|
| ✅ Done | 47 |
| 🚧 WIP | 12 |

# Regex expects plain text
grep -E "Done\s+\d+" file.md  # Misses "✅ Done"

The Solution

Keep machine-consumed files decoration-free:

<!-- Machine-readable version -->
| Status | Count |
|--------|-------|
| Done | 47 |
| WIP | 12 |

If You Need Both

Separate the machine-readable data from the display version:

// data/status.json (machine-readable)
{
  "done": 47,
  "wip": 12
}

// Display layer adds emoji
const statusEmoji = { done: '✅', wip: '🚧' };

What Breaks

File Types to Keep Clean

• JSON configuration
• CSV/TSV data files
• Markdown tables read by scripts
• Log output parsed by aggregators
• YAML consumed by CI/CD

Verification

# Check for common decorations
grep -P '[\x{1F300}-\x{1F9FF}]' file.md  # Emoji
grep -P '[\x{2700}-\x{27BF}]' file.md     # Dingbats

When to Apply

• Any file consumed by scripts or automation
• Data files read by multiple systems
• Content that might be parsed by LLMs

Tags

documentation automation parsing data