markdown-headings

Enforce single H1, heading order, and spacing in Markdown documents.

3|5|Updated Mar 19, 2026

Search Tags:#markdown #consistency #provenance #structure #headings #h1

Ready to run

npx skills add https://github.com/ronniegeraghty/hyoka --skill markdown-headings

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: markdown-headings
Source: https://github.com/ronniegeraghty/hyoka/tree/main/skills/test/markdown-headings
Command: npx skills add https://github.com/ronniegeraghty/hyoka --skill markdown-headings

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This rule set ensures every markdown document uses a correct and consistent heading structure, preventing misformatted or ambiguous content.

Core Features & Use Cases

Enforces exactly one H1 per document, proper level progression, and blank lines around headings.
Adds a provenance marker before the H1 to trace source and intent, ensuring traceability across files.
Use this when authoring new docs, updating guides, or formatting templates to guarantee accessible, well-structured Markdown content.

Quick Start

Apply this rule to a new or existing Markdown document before saving to ensure correct heading hierarchy.

Frequently Asked Questions about markdown-headings

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I enforce correct markdown heading structures in my documents?▼

To enforce correct markdown heading structures, apply automated rules that restrict documents to a single H1 and ensure proper heading level progression. This guarantees accessible content by preventing misformatted or ambiguous heading hierarchies.

What is the correct way to format markdown headings to prevent ambiguous content?▼

Correct markdown heading formatting requires exactly one H1 per document, proper level ordering, and appropriate blank lines around headings. Maintaining this structure prevents ambiguous content and ensures consistent formatting across files.

How do I add provenance markers to trace markdown heading source and intent?▼

To add provenance markers for tracing markdown heading source and intent, insert a specific HTML comment marker immediately above the H1. This traces document source and intent, ensuring traceability across multiple markdown files.

Does this markdown heading validation work for existing guides and templates?▼

Yes, this markdown heading validation works for existing guides and templates. You can apply these rules to existing documents before saving to check level progression and formatting, guaranteeing well-structured markdown content.