Convert HTML Heading Tags (h1-h6) to Markdown Headings

HTML Headings to Markdown

HTML defines six levels of headings with <h1> through <h6> tags. In Markdown, these are represented using hash characters (#) — one hash per heading level.

Conversion Rules

<h1>Main Title</h1>
<h2>Section Title</h2>
<h3>Subsection</h3>
<h4>Sub-subsection</h4>
<h5>Minor Heading</h5>
<h6>Smallest Heading</h6>

Converts to:

# Main Title

## Section Title

### Subsection

#### Sub-subsection

##### Minor Heading

###### Smallest Heading

Each heading level maps directly: <h1> becomes #, <h2> becomes ##, and so on up to <h6> becoming ######.

Handling Attributes

HTML headings often carry attributes like id, class, or style:

<h2 id="getting-started" class="section-title">Getting Started</h2>

Standard Markdown does not support attributes, so they are discarded during conversion:

## Getting Started

Some extended Markdown syntaxes (like Pandoc or markdown-it) support {#id} attribute syntax, but most converters drop attributes by default.

Headings with Inline Content

Headings may contain inline elements such as links, code, or emphasis:

<h2>Install <code>node.js</code> for <em>Development</em></h2>

Converts to:

## Install `node.js` for *Development*

The inline elements are recursively converted to their Markdown equivalents.

Best Practices

• Ensure there is a blank line before and after each heading in the Markdown output.
• Preserve the heading hierarchy from the original HTML — do not flatten or skip levels.
• Use only one # (h1) per document for proper semantic structure.