turbovault_parser/lib.rs
1//! # TurboVault Parser
2//!
3//! Obsidian Flavored Markdown (OFM) parser built on `pulldown-cmark`.
4//!
5//! This crate provides:
6//! - Fast markdown parsing (CommonMark foundation)
7//! - Frontmatter extraction (YAML)
8//! - Obsidian-specific syntax: wikilinks, embeds, callouts, tasks, tags, headings
9//! - Link extraction and resolution
10//!
11//! ## Architecture
12//!
13//! Parser pipeline:
14//! 1. **Frontmatter Extraction**: Using regex for ---YAML---
15//! 2. **Link Parsing**: Wikilinks and embeds
16//! 3. **OFM Elements**: Tags, tasks, callouts, headings with regex
17//!
18//! ## Quick Start
19//!
20//! ```
21//! use turbovault_parser::Parser;
22//! use std::path::PathBuf;
23//!
24//! let content = r#"---
25//! title: My Note
26//! tags: [important, review]
27//! ---
28//!
29//! # Heading
30//!
31//! [[WikiLink]] and [[Other Note#Heading]].
32//!
33//! - [x] Completed task
34//! - [ ] Pending task
35//! "#;
36//!
37//! let path = PathBuf::from("my-note.md");
38//! let result = Parser::parse(&path, content).unwrap();
39//!
40//! // Access parsed components
41//! if let Some(frontmatter) = &result.frontmatter {
42//! println!("Title: {}", frontmatter.title.as_ref().unwrap_or(&"Untitled".to_string()));
43//! }
44//! println!("Links: {:?}", result.links.len());
45//! println!("Tasks: {:?}", result.tasks.len());
46//! ```
47//!
48//! ## Supported OFM Features
49//!
50//! ### Links
51//! - Wikilinks: `[[Note]]`
52//! - Aliases: `[[Note|Alias]]`
53//! - Block references: `[[Note#^blockid]]`
54//! - Heading references: `[[Note#Heading]]`
55//! - Embeds: `![[Note]]`
56//!
57//! ### Frontmatter
58//! YAML frontmatter between `---` delimiters is extracted and parsed.
59//!
60//! ### Elements
61//! - **Headings**: H1-H6 with level tracking
62//! - **Tasks**: Markdown checkboxes with completion status
63//! - **Tags**: Inline tags like `#important`
64//! - **Callouts**: Obsidian callout syntax `> [!TYPE]`
65//!
66//! ## Performance
67//!
68//! The parser uses `pulldown-cmark` for the CommonMark foundation, providing:
69//! - Linear time complexity O(n)
70//! - Zero-copy parsing where possible
71//! - Streaming-friendly architecture
72//!
73//! ## Error Handling
74//!
75//! Parsing errors are wrapped in [`turbovault_core::error::Result`]. Common errors:
76//! - Invalid file paths
77//! - YAML parsing failures in frontmatter
78//! - Invalid unicode in content
79
80pub mod parsers;
81
82pub use parsers::Parser;
83
84pub mod prelude {
85 pub use crate::parsers::Parser;
86 pub use turbovault_core::prelude::*;
87}