docspec 1.7.1

Streaming document conversion: convenience facade re-exporting readers, writers, and event types
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

# `docspec`

Streaming document conversion. Convenience facade re-exporting the DocSpec readers,
writers, and core event types.

Use this crate when you want a single entry point. For the smallest possible dependency
footprint, depend directly on the individual sub-crates (`docspec-core`,
`docspec-markdown-reader`, etc.) instead.

## Usage

```toml
[dependencies]
docspec = { version = "1.5", features = ["markdown", "blocknote"] }
```

```rust
use docspec::readers::MarkdownReader;
use docspec::writers::BlockNoteWriter;
use docspec::{EventSink, EventSource, StackTrackingSink};

let markdown = "# Hello\n\nWorld";
let mut reader = MarkdownReader::from_str(markdown);
let mut buf = Vec::<u8>::new();
let mut writer = StackTrackingSink::new(BlockNoteWriter::new(&mut buf));

while let Some(event) = reader.next_event()? {
    writer.handle_event(event)?;
}
writer.finish()?;
```

## Feature Flags

### Readers

| Feature    | Format                                           | Crate                     |
| ---------- | ------------------------------------------------ | ------------------------- |
| `markdown` | Markdown (CommonMark + GFM tables/strikethrough) | `docspec-markdown-reader` |
| `html`     | HTML (paragraphs only)                           | `docspec-html-reader`     |
| `docx`     | DOCX (paragraphs and text only)                  | `docspec-docx-reader`     |

`DocxReader` is dispatched through `AnyReader::from_reader` and `AnyReader::from_path`.
Use `AnyReader::from_path(InputFormat::Docx, path)` to open a DOCX file, or
`AnyReader::from_reader(InputFormat::Docx, cursor)` to read from an in-memory buffer.

```rust
use docspec::{AnyReader, InputFormat};

# fn main() -> docspec::Result<()> {
let reader = AnyReader::from_path(InputFormat::Docx, "document.docx")?;
# Ok(())
# }
```

### Writers

| Feature            | Format                 | Crate                      |
| ------------------ | ---------------------- | -------------------------- |
| `blocknote-writer` | BlockNote JSON         | `docspec-blocknote-writer` |
| `oxa-writer`       | oxa.dev JSON           | `docspec-oxa-writer`       |
| `html-writer`      | HTML (paragraphs only) | `docspec-html-writer`      |
| `pandoc-native-writer` | Pandoc native block list | `docspec-pandoc-native-writer` |

### Primitives

| Feature | Crate          | Use case                           |
| ------- | -------------- | ---------------------------------- |
| `json`  | `docspec-json` | Building custom JSON-based writers |

### Convenience

| Feature       | Enables                                                       |
| ------------- | ------------------------------------------------------------- |
| `blocknote`   | BlockNote in both directions (writer only until reader lands) |
| `oxa`         | oxa.dev in both directions (writer only until reader lands)   |
| `pandoc-native` | Pandoc native in both directions (writer only until reader lands) |
| `all-readers` | All reader features                                           |
| `all-writers` | All writer features                                           |
| `all-libs`    | All primitive/library features (currently `json`)             |
| `full`        | Everything (`all-readers` + `all-writers` + `all-libs`)       |

Default features are `markdown`, `blocknote`, and `pandoc-native`; disable default features when you need the smallest possible dependency footprint.

## Documentation

See the [main DocSpec repository](https://github.com/docspec/docspec) for the full
project documentation, architecture, and event protocol.