Crate docspec 

DocSpec

A streaming document conversion library. Documents are streams of typed events flowing from EventSource readers to EventSink writers. Readers and writers are fully decoupled — any reader can connect to any writer.

This crate is a thin convenience facade over the modular DocSpec workspace. It re-exports the core event types and traits, plus the optional format readers and writers that you opt into through feature flags.

Feature Flags

Readers

Feature	Format	Re-exports
markdown	Markdown (CommonMark + GFM tables/strikethrough)	readers::MarkdownReader
html	HTML (paragraphs only)	readers::HtmlReader
docx	DOCX (paragraphs and text only)	readers::DocxReader

Note: readers::DocxReader takes a binary file or any Read + Seek source rather than a &str, so it is not dispatched through the text-based AnyReader factory. Construct it directly with DocxReader::from_path or DocxReader::from_reader.

Writers

Feature	Format	Re-exports
blocknote-writer	BlockNote JSON	writers::BlockNoteWriter
oxa-writer	oxa.dev JSON	writers::OxaWriter
html-writer	HTML (paragraphs only)	writers::HtmlWriter

Primitives

Feature	Re-exports
json	json — streaming JSON emission primitives for custom 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)
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)

Choosing the Right Dependency

Use this docspec crate when you want a single convenient entry point and you’re happy to opt into formats via features. For the smallest possible dependency footprint, depend directly on the individual sub-crates (docspec-core, docspec-markdown-reader, etc.) instead.

Quick Start

Add docspec to your Cargo.toml with the features you need:

[dependencies]
docspec = { version = "0.5", features = ["markdown", "blocknote"] }

Convert Markdown to BlockNote JSON:

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

let markdown = "# Hello\n\nWorld";
let mut reader = MarkdownReader::new(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()?;

let _json = String::from_utf8(buf)?;

Re-exports

pub use factory::reader::AnyReader;

pub use factory::writer::AnyWriter;

pub use format::detect_input_format;

pub use format::detect_output_format;

pub use format::InputFormat;

pub use format::OutputFormat;

pub use docspec_json as json;json

Modules

factory

Enum-dispatch factories for document readers and writers.

format

Format detection and conversion helpers.

prelude

Commonly used items, brought into scope with a single import.

readers

Document readers (event sources).

writers

Document writers (event sinks).

Structs

Author

An author with a name and optional email address.

Depth

A saturating u32 counter for nesting-depth tracking.

DocumentMeta

Metadata attached to the document.

Position

The position in a source document where an error occurred.

StackTrackingSink

A wrapper around any EventSink that tracks the nesting stack of open block-level containers and performs event-stream normalization.

TextStyle

Text formatting attributes for an Event::Text event.

Enums

BlockKind

Identifies the kind of block-level container in a document event stream.

Color

An RGB color value.

Error

Errors that can occur during document processing.

Event

A streaming document event.

ImageSource

A reference to an image asset, either embedded or external.

ListStyleType

The specific visual style for a list.

TableHeaderScope

Scope of a table header cell.

TextAlignment

Text alignment options for paragraphs.

Traits

AssetProvider

Provides access to binary assets referenced in the event stream.

EventSink

Consumes a stream of crate::Events to produce output.

EventSource

Produces a stream of crate::Events from a document source.

Functions

block_kind_for_end

Returns the BlockKind for an end event, or None if the event is not a block end.

block_kind_for_start

Returns the BlockKind for a start event, or None if the event is not a block start.

pipe

Pull events from source and push them into sink until the source drains, then call EventSink::finish on the sink.

Type Aliases

Result

Result type alias for DocSpec operations.