docs: prevent redundant first headings

[youssefea]

What changed? Why?

• Add a blocking heading/redundant-page-title rule to the MDX linter used by Docs Style / Conformance.
• Normalize punctuation, Markdown formatting, case, diacritics, and &/and, and strip conservative introductory phrases such as “What Is” and “Introduction to” before comparing the first body heading with the frontmatter title.
• Keep the comparison intentionally narrow so real subsections such as “L2 Contract Addresses” on “Contract Addresses” remain valid.
• Remove the three current corpus violations: “Design Goals”, “What Is Transaction Finality?”, and “What Are Builder Codes”.
• Reduce the content container top margin for both prose and headings, and remove the extra top margin from an H2 that is the first MDX element. Later section spacing is unchanged.
• Document the new rule in the content guidelines and linter reference.
• Add scripts/lint-mdx.js to the IA CI Configuration protected paths so future guardrail changes require three Writer approvals.

Notes to reviewers

Mintlify already renders the frontmatter title as the page H1. The new rule prevents authors from immediately rendering the same title again as the first H2.

The spacing selectors use the stable #content ID. They tighten the transition into all MDX content, with an additional reset when the first element is an H2:

#content { margin-top: 1rem; }
#content > h2:first-child { margin-top: 0; }

In a local Mintlify preview, both description-to-prose and description-to-first-heading spacing now measure 36px. Prose decreased from 52px to 36px, and a direct first H2 decreased from 84px to 36px. Headings that follow body content and later headings are unchanged.

How has it been tested?

• npm test — 85/85 tests pass.
• node scripts/lint-mdx.js all --format=github — 313 published MDX pages checked with 0 errors.
• git diff --check
• Local Mintlify preview, including a before/after computed-layout measurement.

Screenshots

Validated in a local Mintlify preview. The visible gap is now 36px for both prose and a first heading, and the duplicate headings no longer render on the three affected pages.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
base	🟢 Ready	View Preview	Sep 14, 2026, 4:15 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[cb-heimdall]

✅ Heimdall Review Status

Requirement	Status	More Info
Reviews	✅ 3/1	Denominator calculation Show calculation 1 if user is bot 0 1 if user is external 0 2 if repo is sensitive 0 From .codeflow.yml 1 Additional review requirements Show calculation Max 0 0 From CODEOWNERS 0 Global minimum 0 Max 1 1 1 if commit is unverified 0 Sum 1