Fix H1 Command

Removes duplicate H1 headings that repeat the frontmatter title field in MDX documentation files.

Usage

writechoice fix h1 [options]

Options

Option	Alias	Description	Default
--file <path>	-f	Fix a single MDX file	-
--dir <path>	-d	Fix MDX files in a specific directory	-
--dry-run	-	Preview changes without writing files	false
--quiet	-	Suppress terminal output	false

Why This Is Needed

Mintlify automatically renders the frontmatter title as a visible page heading. If a file also contains a Markdown H1 (# Title) right after the frontmatter with the same text, the title appears twice on the page. This command removes the redundant H1.

What Gets Removed

The first non-empty line after frontmatter is removed only if it is an H1 that exactly matches the frontmatter title (case-sensitive, whitespace-trimmed). The blank line immediately following is also removed.

<!-- Before -->
---
title: Getting Started
---

# Getting Started

Welcome to the documentation.

<!-- After -->
---
title: Getting Started
---

Welcome to the documentation.

What Is Left Unchanged

• Files with no frontmatter or no title field
• H1s that don't exactly match the frontmatter title
• H1s that appear anywhere other than the first non-empty line after frontmatter

Examples

# Preview changes before writing
writechoice fix h1 --dry-run

# Fix all MDX files in the current directory
writechoice fix h1

# Fix a specific directory
writechoice fix h1 -d docs/api

Config File

{
  "h1": {
    "dir": "docs",
    "dry-run": false,
    "quiet": false
  }
}

Safety

• Only removes the H1 if it exactly matches the frontmatter title
• Idempotent: running again on an already-fixed file produces no changes
• Use --dry-run to preview before writing
• Revert with git checkout . if needed