How Humanizer File Mode Preserves Code Blocks, Inline Code, YAML, and Metadata

Humanizer's file mode processes markdown documents by parsing content into logical segments and applying rewrite logic exclusively to prose sections while strictly preserving code fences, inline code spans, YAML front-matter, and link targets according to the specifications in SKILL.md.

The blader/humanizer repository provides a markdown-based skill designed to eliminate AI-generated artifacts from text. When operating in file mode, Humanizer activates a specialized execution path that processes entire documents while maintaining the integrity of technical elements, ensuring that only narrative prose undergoes transformation while code and metadata remain untouched.

How Humanizer File Mode Works

Segment Parsing and Isolation

Humanizer initiates file mode when a user supplies a filename via CLI or API. The system parses the input into distinct logical segments including code fences, inline code spans, YAML front-matter, and plain prose. This segmentation occurs before any text transformation begins, creating isolated content boundaries that the rewrite engine respects during processing.

Selective Rewrite Logic

According to the skill definition in SKILL.md at line 50, the final rewrite must "Keep code blocks, inline code, commands, paths, YAML metadata, data, and link targets unchanged"【/cache/repos/github.com/blader/humanizer/main/SKILL.md:50】. The engine applies stylistic modifications only to segments identified as prose, deliberately bypassing any content recognized as code or structured data. This selective rewrite logic ensures that technical formatting remains untouched while AI-style phrasing in narrative text gets simplified.

Protected Elements in File Mode

YAML Front-Matter and Metadata

The file mode explicitly shields YAML front-matter from modification. Version metadata such as metadata.version: "3.0.0" defined in SKILL.md and user-defined front-matter blocks in processed files remain intact. This preservation ensures document configuration, versioning information, and structured metadata stay exactly as specified by the author.

Fenced Code Blocks

Fenced code blocks delimited by triple backticks receive complete protection during processing. The parser identifies these regions using markdown syntax patterns and excludes them from the rewrite pipeline. This guarantees that indentation, syntax highlighting language tags, and the actual code content remain unaltered regardless of how the surrounding text transforms.

Inline Code and Link Targets

Single-backtick inline code spans and hyperlink targets undergo preservation as well. Whether referencing package names like npm install humanizer or URLs like https://github.com/blader/humanizer, these elements maintain their original formatting. The system recognizes backtick delimiters and URL patterns to ensure these technical references survive the rewrite process while surrounding prose receives optimization.

Practical Examples of File Mode Preservation

Consider the following input file containing mixed content types:

---
title: My Project
version: 1.0
---

```python
def hello():
    print("Hello, world!")

The AI often uses the phrase "the real win." This is a tell.

After processing with `humanizer --file README.md`, the output demonstrates selective modification:

```markdown
---
title: My Project
version: 1.0
---

```python
def hello():
    print("Hello, world!")

The AI often uses the phrase "the real win." This is a tell.

Notice that the YAML front-matter remains unchanged, the Python code block preserves its original formatting, and only the bold formatting in the prose section has been removed.

For inline elements, input containing:

```markdown
Run `npm install humanizer` to add the package.  
See the documentation at https://github.com/blader/humanizer.

Maintains the backtick-delimited command and the URL exactly while simplifying any AI-style verbosity in the surrounding sentences.

Implementation Architecture

The preservation mechanism relies on prompt-based enforcement rather than compiled code logic. The agents/openai.yaml file provides the default prompt templates that instruct the underlying language model to recognize and protect specific syntactic patterns. This architecture ensures that README.md documentation and skill definitions remain consistent with the actual processing behavior defined in the core skill files.

Summary

• Segment-based parsing isolates code blocks, YAML, and prose into distinct processing units before transformation begins.
• Selective rewriting applies AI-tell removal only to narrative text while preserving technical elements verbatim.
• YAML front-matter including version metadata remains untouched to maintain document configuration integrity.
• Fenced and inline code keep their original formatting, indentation, and content regardless of surrounding text changes.
• Prompt-level enforcement in SKILL.md and agents/openai.yaml guarantees consistent behavior without requiring compiled code dependencies.

Frequently Asked Questions

How does Humanizer distinguish between prose and code blocks?

Humanizer uses markdown syntax patterns to identify triple-backtick fences, single backtick spans, and YAML delimiters (---). These patterns trigger segment isolation before the rewrite engine processes the content, ensuring code regions receive pass-through treatment while prose undergoes modification.

Will Humanizer file mode modify my document's metadata?

No. The file mode explicitly preserves YAML front-matter and metadata blocks. As documented in SKILL.md, the system keeps "YAML metadata, data, and link targets unchanged," ensuring that titles, versions, and configuration fields remain exactly as authored without alteration.

Can I use file mode with non-markdown files?

File mode is optimized for markdown structures and relies on markdown-specific syntax markers to identify protected regions. While the CLI may accept any file type via humanizer --file <filename>, the preservation logic specifically targets markdown code fences, inline code syntax, and YAML front-matter delimiters for accurate processing.

Where is the file mode behavior documented?

The authoritative specification resides in SKILL.md at line 50 within the blader/humanizer repository. Additional usage examples appear in README.md, while the prompt templates that enforce these rules are defined in agents/openai.yaml.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}