Zig Markdown Parser

A fast, zero-copy markdown parser written in Zig that converts markdown text into an Abstract Syntax Tree (AST).

Project Status

⚠️ Early Development - This project is in the planning phase with comprehensive documentation but no parser implementation yet.

Features (Planned)

• Pure Parsing: Converts markdown to AST without rendering
• Zero-Copy Design: Minimizes allocations by referencing original text
• Single-Pass Parsing: Efficient one-pass parsing algorithm
• Extensible Architecture: Easy to add custom markdown extensions
• Memory Safe: Leverages Zig's compile-time safety guarantees
• CommonMark Compliant: Targeting full CommonMark specification compliance

Requirements

• Zig 0.15.0-dev.847+850655f06 or newer

Installation

Clone the repository:

git clone https://github.com/[username]/zig-markdown-parser.git
cd zig-markdown-parser

Building

# Build the project (both library and executable)
zig build

# Run the CLI executable
zig build run

# Run all tests
zig build test

# Build with specific optimization
zig build -Doptimize=ReleaseFast
zig build -Doptimize=ReleaseSafe
zig build -Doptimize=ReleaseSmall
zig build -Doptimize=Debug

Usage (Planned API)

const std = @import("std");
const markdown = @import("zig-markdown-parser");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    const input = "# Hello, World!\n\nThis is a **markdown** document.";
    const ast = try markdown.parse(allocator, input, .{});
    defer ast.deinit(allocator);

    // Traverse the AST for your purposes
    // (HTML generation, analysis, transformation, etc.)
}

Architecture

The parser follows a three-stage pipeline:

Input (string) → Lexer (tokens) → Parser (AST)

Project Structure

src/
├── main.zig      # CLI entry point
├── root.zig      # Library entry point
├── lexer.zig     # Tokenization (planned)
├── parser.zig    # AST construction (planned)
├── ast.zig       # AST node definitions (planned)
├── token.zig     # Token types (planned)
├── utils.zig     # Shared utilities (planned)
└── errors.zig    # Error handling (planned)

Development Roadmap

Phase 1: Basic Block Elements

Paragraphs
Headers (H1-H6)
Lists (ordered/unordered)
Code blocks
Block quotes

Phase 2: Inline Elements

Emphasis (bold/italic)
Links
Code spans
Images

Phase 3: Advanced Features

Tables (GFM)
Nested structures
HTML blocks

Phase 4: CommonMark Compliance

Full specification compliance
Edge case handling
Comprehensive test suite

Phase 5: Performance Optimization

Benchmarking
Memory optimization
SIMD optimizations

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Inspired by the CommonMark specification
• Built with the Zig programming language