mdka 2.0.2

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
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

# Usage — Rust

## Basic Conversion

```rust
use mdka::html_to_markdown;

fn main() {
    let html = r#"
        <h1>Getting Started</h1>
        <p>mdka converts <strong>HTML</strong> to <em>Markdown</em>.</p>
        <ul>
            <li>Fast</li>
            <li>Configurable</li>
            <li>Crash-resistant</li>
        </ul>
    "#;

    let md = html_to_markdown(html);
    println!("{md}");
}
```

Output:

```
# Getting Started

mdka converts **HTML** to *Markdown*.

- Fast
- Configurable
- Crash-resistant
```

## Conversion with Options

Use `html_to_markdown_with` to control the conversion pipeline via
[`ConversionOptions`](../api/options.md).

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

// Strip navigation and extract body text — good for LLM input
let opts = ConversionOptions::for_mode(ConversionMode::Minimal)
    .drop_interactive_shell(true);

let html = r#"
    <header><nav><a href="/">Home</a></nav></header>
    <main>
        <article>
            <h1>Article Title</h1>
            <p>The main content of the page.</p>
        </article>
    </main>
    <footer>Copyright 2025</footer>
"#;

let md = html_to_markdown_with(html, &opts);
assert!(md.contains("# Article Title"));
assert!(!md.contains("Home"));       // nav removed
assert!(!md.contains("Copyright"));  // footer removed
```

## Converting a Single File

```rust
use mdka::html_file_to_markdown;

// Output goes to the same directory as the input: page.html → page.md
let result = html_file_to_markdown("page.html", None::<&str>)?;
println!("{} → {}", result.src.display(), result.dest.display());

// Output goes to a specific directory
let result = html_file_to_markdown("page.html", Some("out/"))?;
```

## Bulk Parallel Conversion

```rust
use mdka::html_files_to_markdown;
use std::path::Path;

let files = vec!["a.html", "b.html", "c.html"];
let out_dir = Path::new("out/");
std::fs::create_dir_all(out_dir)?;

for (src, result) in html_files_to_markdown(&files, out_dir) {
    match result {
        Ok(dest) => println!("{} → {}", src, dest.display()),
        Err(e)   => eprintln!("Error: {src}: {e}"),
    }
}
```

Conversion runs in parallel using [rayon](https://crates.io/crates/rayon).
The number of threads defaults to the number of logical CPU cores.

## Bulk Conversion with Options

```rust
use mdka::{html_files_to_markdown_with};
use mdka::options::{ConversionMode, ConversionOptions};
use std::path::Path;

let opts = ConversionOptions::for_mode(ConversionMode::Semantic);
let files = vec!["a.html", "b.html"];
let results = html_files_to_markdown_with(&files, Path::new("out/"), &opts);
```

## Conversion Modes at a Glance

| Mode | Best for |
|---|---|
| `Balanced` | General use; default |
| `Strict` | Debugging, diff comparison |
| `Minimal` | LLM pre-processing, compression |
| `Semantic` | SPA content, accessibility-aware output |
| `Preserve` | Archiving, audit trails |

See [Conversion Modes](../api/modes.md) for full details.

## Error Handling

```rust
use mdka::{html_file_to_markdown, MdkaError};

match html_file_to_markdown("missing.html", None::<&str>) {
    Ok(result) => println!("→ {}", result.dest.display()),
    Err(MdkaError::Io(e)) => eprintln!("IO error: {e}"),
}
```

`MdkaError` currently has one variant: `Io`, wrapping `std::io::Error`.
`html_to_markdown` and `html_to_markdown_with` are infallible — they always
return a `String` and never panic on any input, no matter how malformed.