<!-- source-hash: 7c9c0c76751534f9471aac4fddb8f3e7 -->
Parses markdown content line-by-line to extract heading sections for navigation, returning structured metadata including IDs, titles, and heading levels.

## Key Components

### Interfaces

- **`MarkdownSection`** — Output shape with `id` (URL-safe slug), `title` (cleaned text), and `level` (heading depth 1–6)
- **`ExtractSectionsOptions`** — Configuration for extraction behavior (see defaults below)

### Function

- **`extractSections(markdown, options?)`** — Main export. Iterates over lines, skips fenced code blocks and YAML frontmatter, matches heading patterns up to `maxLevel`, and returns a `MarkdownSection[]`

### Default Options

| Option | Default | Description |
|---|---|---|
| `maxLevel` | `2` | Include H1–H2 only |
| `removeEmojis` | `true` | Strip emoji from generated IDs |
| `handleDuplicateIds` | `true` | Append `-2`, `-3`, etc. for duplicate slugs |
| `stripFormattingMarkers` | `true` | Remove bold/italic/code markers from titles |
| `skipCodeAndYamlBlocks` | `true` | Ignore headings inside code fences or frontmatter |

## Usage Example

```typescript
import { extractSections } from './markdown-section-extractor'

const markdown = `
---
title: Guide
---

# Introduction

## **Getting Started**

## Getting Started

\`\`\`bash
# This heading is skipped
\`\`\`

### Deep Section
`

const sections = extractSections(markdown, { maxLevel: 3 })
// [
//   { id: 'introduction',      title: 'Introduction',     level: 1 },
//   { id: 'getting-started',   title: 'Getting Started',  level: 2 },
//   { id: 'getting-started-2', title: 'Getting Started',  level: 2 },
//   { id: 'deep-section',      title: 'Deep Section',     level: 3 },
// ]
```

> **Note:** ID generation lowercases text, strips non-word characters, and replaces spaces with hyphens. Empty IDs fall back to `section-N`. Depends on [`stripInlineMarkdown`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/markdown-to-plain.ts) for title cleanup.