Summary

The extension replaces |placeholder| patterns with configured values. Substitution logic is well-suited for property-based testing.

Benefits

• Invariants: For any template and substitution map, all |key| occurrences should be replaced with the value
• Flag behavior: When substitutions are disabled, output should match input (no replacement)
• Edge cases: Empty replacement values, Unicode placeholders, nested/overlapping patterns, placeholder names that appear in replacement values
• Idempotency: When replacement value does not contain placeholder syntax, substituting twice could be tested

Suggested properties

1. For template containing |key| and substitutions[key] = value, output has all occurrences replaced
2. Substitution preserves length or structure in predictable ways (e.g. no insertion of extra content)
3. :nosubstitutions: / :nocontent-substitutions: prevents replacement

Focus areas

• replace:: directive handling
• literalinclude with :content-substitutions:
• Path substitutions in literalinclude / image
• MyST documents with myst_substitutions

Note

.hypothesis/ is already in .gitignore.