Struct MarkdownParser 

pub struct MarkdownParser { /* private fields */ }

A tree-sitter based markdown parser.

Provides structured parsing of markdown documents with heading hierarchy extraction, content block identification, and diagnostic reporting. The parser is designed to be resilient to malformed input while providing detailed structural information.

Parsing Strategy

The parser uses tree-sitter’s markdown grammar to:

1. Build a complete syntax tree of the document
2. Walk the tree to identify heading nodes and their levels
3. Extract content blocks between headings
4. Build hierarchical table of contents structure
5. Generate diagnostics for quality issues

Reusability

Parser instances can be reused for multiple documents, but are not thread-safe. The internal tree-sitter parser maintains mutable state across parse operations.

Memory Management

The parser automatically manages memory for syntax trees and intermediate structures. Large documents may temporarily use significant memory during parsing, but this is released after the parse() method returns.

Implementations

impl MarkdownParser

pub fn new() -> Result<Self>

Create a new markdown parser instance.

Initializes the tree-sitter parser with the markdown grammar. This operation may fail if the tree-sitter language cannot be loaded properly.

Returns

Returns a new parser instance ready for use.

Errors

Returns an error if:

• The tree-sitter markdown language cannot be loaded
• The parser cannot be initialized with the markdown grammar
• System resources are insufficient for parser creation

Examples

use blz_core::{MarkdownParser, Result};

// Create a new parser
let mut parser = MarkdownParser::new()?;

// Parser is now ready to parse markdown content
let result = parser.parse("# Hello World\n\nContent here.")?;
assert!(!result.heading_blocks.is_empty());

Resource Usage

Creating a parser allocates approximately 1-2MB of memory for the grammar and internal structures. This overhead is amortized across multiple parse operations.

pub fn parse(&mut self, text: &str) -> Result<ParseResult>

Parse markdown text into structured components.

Performs complete analysis of the markdown document, extracting heading hierarchy, content blocks, table of contents, and generating diagnostics for any issues found.

Arguments

• text - The markdown content to parse (UTF-8 string)

Returns

Returns a ParseResult containing:

• Structured heading blocks with content and line ranges
• Hierarchical table of contents
• Diagnostic messages for any issues found
• Line count and other metadata

Errors

Returns an error if:

• The text cannot be parsed by tree-sitter (very rare)
• Memory is exhausted during parsing of extremely large documents
• Internal parsing structures cannot be built

Note: Most malformed markdown will not cause errors but will generate diagnostics.

Examples

use blz_core::{MarkdownParser, Result};

let mut parser = MarkdownParser::new()?;

// Parse simple markdown
let result = parser.parse(r#"

This is an introduction section.

# Getting Started

Here's how to get started:

1. First step
2. Second step

## Prerequisites

You'll need these tools.
"#)?;

// Check the results
// The parser creates one block per heading with content until the next heading
assert!(result.heading_blocks.len() >= 2); // At least Introduction and Getting Started
assert!(!result.toc.is_empty());
// Line count represents total lines in the document
assert!(result.line_count > 0);

// Look for any parsing issues
for diagnostic in &result.diagnostics {
    println!("{:?}: {}", diagnostic.severity, diagnostic.message);
}

Performance Guidelines

• Documents up to 1MB: Parse in under 50ms
• Documents up to 10MB: Parse in under 500ms
• Very large documents: Consider streaming or chunking for better UX

Memory Usage

Memory usage during parsing is approximately:

• Small documents (< 100KB): ~2x document size
• Large documents (> 1MB): ~1.5x document size
• Peak usage occurs during tree traversal and structure building