mdka 2.0.3

HTML to Markdown converter
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

# ConversionOptions

```rust
pub struct ConversionOptions {
    pub mode: ConversionMode,

    // Attribute retention
    pub preserve_ids:             bool,
    pub preserve_classes:         bool,
    pub preserve_data_attrs:      bool,
    pub preserve_aria_attrs:      bool,
    pub preserve_unknown_attrs:   bool,

    // Pre-processing behaviour
    pub drop_presentation_attrs:  bool,
    pub drop_interactive_shell:   bool,
    pub unwrap_unknown_wrappers:  bool,
}
```

`ConversionOptions` controls every detail of the pre-processing pipeline.
You rarely need to set individual fields — start with a mode and override
only what differs from the default for that mode.

## Creating Options

### From a mode (recommended)

```rust
use mdka::options::{ConversionMode, ConversionOptions};

let opts = ConversionOptions::for_mode(ConversionMode::Minimal);
```

`for_mode` returns sensible defaults for the chosen mode. See the table below.

### Builder methods

```rust
let opts = ConversionOptions::for_mode(ConversionMode::Balanced)
    .drop_interactive_shell(true)   // also strip nav/header/footer/aside
    .preserve_ids(false)            // don't keep id= attributes
    .preserve_aria_attrs(true);     // (already true in Balanced, shown for clarity)
```

### Default

```rust
let opts = ConversionOptions::default(); // equivalent to for_mode(Balanced)
```

## Field Defaults by Mode

| Field | Balanced | Strict | Minimal | Semantic | Preserve |
|---|---|---|---|---|---|
| `preserve_ids` | ✅ | ✅ | ❌ | ✅ | ✅ |
| `preserve_classes` | ❌ | ✅ | ❌ | ❌ | ✅ |
| `preserve_data_attrs` | ❌ | ✅ | ❌ | ❌ | ✅ |
| `preserve_aria_attrs` | ✅ | ✅ | ❌ | ✅ | ✅ |
| `preserve_unknown_attrs` | ❌ | ✅ | ❌ | ❌ | ✅ |
| `drop_presentation_attrs` | ✅ | ❌ | ✅ | ✅ | ❌ |
| `drop_interactive_shell` | ❌ | ❌ | ✅ | ❌ | ❌ |
| `unwrap_unknown_wrappers` | ❌ | ❌ | ✅ | ✅ | ❌ |

## Field Reference

### `mode`
The [ConversionMode](./modes.md) this options object was built from.
Changing `mode` after construction does not re-apply mode defaults
to the other fields — use `for_mode()` again instead.

### `preserve_ids`
Whether to keep `id="…"` attributes in the pre-processed DOM.
Useful when the output is rendered in a context that relies on
anchor links (`#section-name`).

### `preserve_classes`
Whether to keep `class="…"` attributes.
Rarely useful in Markdown output, but can help when feeding the
Markdown back into an HTML renderer that applies CSS.

### `preserve_data_attrs`
Whether to keep `data-*` custom attributes.
Mostly relevant for `Strict` and `Preserve` modes.

### `preserve_aria_attrs`
Whether to keep `aria-*` accessibility attributes.
Enabled by default in `Balanced`, `Strict`, `Semantic`, and `Preserve`.
The attributes themselves do not appear in Markdown output, but they
are used by the `Semantic` mode's conversion logic.

### `preserve_unknown_attrs`
Whether to keep attributes not otherwise handled (everything except
`href`, `src`, `alt`, `title`, `aria-*`, `data-*`, `id`, `class`, `style`).

### `drop_presentation_attrs`
Whether to remove `style` and other purely visual attributes during pre-processing.
Enabled in `Balanced`, `Minimal`, and `Semantic`.

### `drop_interactive_shell`
Whether to remove `<nav>`, `<header>`, `<footer>`, and `<aside>` elements
**and all their children**.
Useful for content extraction from full web pages.
Disabled by default in all modes; opt in explicitly.

### `unwrap_unknown_wrappers`
Whether to replace generic container elements (`<div>`, `<span>`,
`<section>`, `<article>`, `<main>`) with their children when they
carry no structural meaning. Enabled in `Minimal` and `Semantic`.