tdoc/lib.rs
1//! tdoc is a toolkit for building, parsing, formatting, and exporting documents
2//! across FTML, HTML, Markdown, and Gemini.
3//!
4//! The crate is centered around three core concepts:
5//! - [`Document`], [`Paragraph`], and [`Span`], which form an in-memory tree
6//! representation of document content.
7//! - Format modules (see [`ftml`], [`html`], [`markdown`], and [`gemini`]) that
8//! provide both parsers and writers for each external format.
9//! - A [`formatter`] for rendering the tree to richly styled terminal output.
10//!
11//! Checklists (Markdown `- [ ]` entries or HTML `<input type="checkbox">`
12//! lists) map to [`ParagraphType::Checklist`] nodes that store [`ChecklistItem`]
13//! children. Nested checklist items are preserved end-to-end so complex task
14//! hierarchies round-trip across every parser and writer.
15//!
16//! Definition lists (HTML `<dl>`, or the PHP Markdown Extra `Term` / `:
17//! definition` syntax) map to [`ParagraphType::DefinitionList`] nodes holding
18//! [`DefinitionItem`] children, each pairing one or more terms with a single
19//! definition made of block paragraphs. Unlike checklists, they do not survive
20//! every format: FTML and Gemtext have no such element, so those writers
21//! flatten the structure into text, and Markdown cannot express several terms
22//! sharing one definition. See the
23//! [README](https://github.com/roblillack/tdoc#definition-lists) for what each
24//! writer does.
25//!
26//! Most applications start by building a [`Document`] manually or converting
27//! some source text via one of the format modules, manipulate or inspect the
28//! tree, and finally render it with [`ftml::Writer`], [`html::Writer`], or
29//! [`formatter::Formatter`].
30
31mod macros;
32
33pub mod document;
34pub mod formatter;
35pub mod ftml;
36pub mod gemini;
37pub mod html;
38pub mod inline;
39pub mod markdown;
40pub mod metadata;
41pub mod pager;
42pub mod paragraph;
43pub mod test_helpers;
44
45pub use document::Document;
46pub use inline::{InlineStyle, Span};
47pub use pager::*;
48pub use paragraph::{ChecklistItem, DefinitionItem, Paragraph, ParagraphType, TableCell, TableRow};
49
50/// Convenience result type used across parsing and writing APIs.
51pub type Result<T> = std::result::Result<T, Box<dyn std::error::Error + Send + Sync>>;