quillmark_core/lib.rs
1//! # Quillmark Core Overview
2//!
3//! Core types and functionality for the Quillmark format-first Markdown rendering system.
4//!
5//! ## Features
6//!
7//! This crate provides the foundational types and traits for Quillmark:
8//!
9//! - **Parsing**: card-yaml block extraction (`~~~` metadata blocks)
10//! - **Format model**: [`Quill`] type for managing format bundles with in-memory file system
11//! - **Backend trait**: Extensible interface for implementing output format backends
12//! - **Error handling**: Structured diagnostics with source location tracking
13//! - **Utilities**: TOML⇄YAML conversion helpers
14//!
15//! ## Quick Start
16//!
17//! ```no_run
18//! use quillmark_core::Document;
19//!
20//! // Parse markdown with a card-yaml metadata block
21//! let markdown = "~~~\n$quill: my_quill\n$kind: main\ntitle: Example\n~~~\n\n# Content";
22//! let doc = Document::from_markdown(markdown).unwrap();
23//! let title = doc.main()
24//! .payload()
25//! .get("title")
26//! .and_then(|v| v.as_str())
27//! .unwrap_or("Untitled");
28//! assert_eq!(title, "Example");
29//! ```
30//!
31//! ## Architecture
32//!
33//! The crate is organized into modules:
34//!
35//! - [`document`]: Markdown parsing with card-yaml block support
36//! - [`backend`]: Backend trait for output format implementations
37//! - [`error`]: Structured error handling and diagnostics
38//! - [`types`]: Core rendering types (OutputFormat, Artifact, RenderOptions)
39//! - [`quill`]: Quill bundle and related types
40//!
41//! ## Further Reading
42//!
43//! - [markdown-spec.md](https://github.com/quillmark-org/quillmark/blob/main/prose/references/markdown-spec.md) - Quillmark Markdown parsing specification
44//! - [Examples](https://github.com/quillmark-org/quillmark/tree/main/crates/core/examples) - Working examples
45
46pub mod document;
47pub use document::{
48 Card, CardWire, Document, EditError, ParseOutput, Payload, PayloadItem, PayloadItemWire,
49 SeedOverlay, WireError,
50};
51
52pub mod backend;
53pub use backend::Backend;
54
55pub mod error;
56pub use error::{Diagnostic, Location, ParseError, RenderError, RenderResult, Severity};
57
58pub mod types;
59pub use types::{Artifact, OutputFormat, RenderOptions};
60
61pub mod session;
62pub use session::RenderSession;
63
64pub mod quill;
65pub use quill::{zero_value, FileTreeNode, Quill, QuillIgnore, STANDARD_METADATA_KEYS};
66
67pub mod value;
68pub use value::{json_depth_exceeds, PathSegment, QuillValue};
69
70pub mod normalize;
71
72pub mod version;
73pub use version::{quill_ref_hint, QuillReference, Version, VersionSelector};