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 vault_path = PathBuf::from("/vault");
38//! let parser = Parser::new(vault_path);
39//!
40//! let path = PathBuf::from("my-note.md");
41//! if let Ok(result) = parser.parse_file(&path, content) {
42//! // Access parsed components
43//! if let Some(frontmatter) = &result.frontmatter {
44//! println!("Frontmatter data: {:?}", frontmatter.data);
45//! }
46//! println!("Links: {}", result.links.len());
47//! println!("Tasks: {}", result.tasks.len());
48//! }
49//! ```
50//!
51//! ## Supported OFM Features
52//!
53//! ### Links
54//! - Wikilinks: `[[Note]]`
55//! - Aliases: `[[Note|Alias]]`
56//! - Block references: `[[Note#^blockid]]`
57//! - Heading references: `[[Note#Heading]]`
58//! - Embeds: `![[Note]]`
59//!
60//! ### Frontmatter
61//! YAML frontmatter between `---` delimiters is extracted and parsed.
62//!
63//! ### Elements
64//! - **Headings**: H1-H6 with level tracking
65//! - **Tasks**: Markdown checkboxes with completion status
66//! - **Tags**: Inline tags like `#important`
67//! - **Callouts**: Obsidian callout syntax `> [!TYPE]`
68//!
69//! ## Performance
70//!
71//! The parser uses `pulldown-cmark` for the CommonMark foundation, providing:
72//! - Linear time complexity O(n)
73//! - Zero-copy parsing where possible
74//! - Streaming-friendly architecture
75//!
76//! ## Error Handling
77//!
78//! Parsing errors are wrapped in [`turbovault_core::error::Result`]. Common errors:
79//! - Invalid file paths
80//! - YAML parsing failures in frontmatter
81//! - Invalid unicode in content
82
83pub mod parsers;
84
85pub use parsers::Parser;
86
87pub mod prelude {
88 pub use crate::parsers::Parser;
89 pub use turbovault_core::prelude::*;
90}