mdka 1.4.0

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

# mdka
**HTML to Markdown (MD)** converter written in [Rust](https://www.rust-lang.org/).

[![crates.io](https://img.shields.io/crates/v/mdka?label=latest)](https://crates.io/crates/mdka)
[![Documentation](https://docs.rs/mdka/badge.svg?version=latest)](https://docs.rs/mdka/latest)
[![License](https://img.shields.io/github/license/nabbisen/mdka-rs)](https://github.com/nabbisen/mdka-rs/blob/main/LICENSE)
[![Dependency Status](https://deps.rs/crate/mdka/latest/status.svg)](https://deps.rs/crate/mdka/latest)

## Summary

A kind of text manipulator named mdka. "ka" means "化 (か)" pointing to conversion.    
Designed with in mind:

- Fast speed
- Low memory consumption
- Easy usage

## Usage

### Executable

[Releases](https://github.com/nabbisen/mdka-rs/releases)' **Assets** offer executables for multiple platforms.

```console
$ ./mdka <html-text>
converted-to-markdown-text will be printed
```

#### Help

```console
$ ./mdka -h
Usage:
  -h, --help             : Help is shown.
  <html_text>            : Direct parameter is taken as HTML text to be converted. Either this or <html_filepath> is required.
  -i <html_filepath>     : Read HTML text from it. Optional.
  -o <markdown_filepath> : Write Markdown result to it. Optional.
  --overwrites           : Overwrite if Markdown file exists. Optional.

Examples:
  ./mdka "<p>Hello, world.</p>"
  ./mdka -i input.html
  ./mdka -o output.md "<p>Hello, world.</p>"
  ./mdka -i input.html -o output.md --overwrites
```

### Development with Rust and cargo

`Cargo.toml`

```toml
[dependencies]
mdka = "1"
```

`awesome.rs`

```rust
use mdka::from_html

fn awesome_fn() {
    let input = r#"
<h1>heading 1</h1>
<p>Hello, world.</p>"#;
    let ret = from_html(input);
    println!("{}", ret);
    // # heading 1
    // 
    // Hello, world.
    // 
}
```

### Python integration

Bindings for Python are supported. Python scripts can import this Rust library to use the function(s).

Install:

```console
$ pip install mdka
```

`awesome.py`

#### Convert from HTML text

```python
from mdka import md_from_html

print(md_from_html("<p>Hello, world.</p>"))
# Hello, world.
# 
```

#### Convert from HTML file

```python
from mdka import md_from_file

print(md_from_file("tests/fixtures/simple-01.html"))
# Hello, world.
# 
```

#### Convert from HTML text and write the result to file

```python
from mdka import md_from_html_to_file

md_from_html_to_file("<p>Hello, world.</p>", "tests/tmp/out.md", False) # third parameter is `overwrites` Boolean
```

#### Convert from HTML file and write the result to file

```python
from mdka import md_from_file_to_file

md_from_file_to_file("tests/fixtures/simple-01.html", "tests/tmp/out.md", False) # third parameter is `overwrites` Boolean
```

## Acknowledgements

Depends on [Servo](https://servo.org/)'s [html5ever](https://github.com/servo/html5ever) / markup5ever.
Also, on [PyO3](https://github.com/PyO3)'s [pyo3](https://github.com/PyO3/pyo3) / [maturin](https://github.com/PyO3/maturin) on bindings for Python.