Overview

Relevant source files

• .beads/issues.jsonl
• .claude/hooks/format-rust.sh
• .claude/settings.json
• CLAUDE.md
• Cargo.lock
• Cargo.toml
• LICENSE
• README.md
• claude-notes/plans/2026-03-09-xtask-verify-ci-parity.md
• claude-notes/plans/2026-03-20-actor-identity-mapping.md
• crates/comrak-to-pandoc/Cargo.toml
• crates/experiments/reconcile-viewer/Cargo.toml
• crates/experiments/reconcile-viewer/src/main.rs
• crates/pampa/Cargo.toml
• crates/pampa/README.md
• crates/pampa/fuzz/Cargo.toml
• crates/pampa/src/bin/ast_reconcile.rs
• crates/pampa/src/pandoc/treesitter_utils/language_specifier.rs
• crates/quarto-ast-reconcile/Cargo.toml
• crates/quarto-citeproc/Cargo.toml
• crates/quarto-pandoc-types/Cargo.toml
• crates/quarto-pandoc-types/src/lib.rs
• crates/tree-sitter-qmd/README.md
• crates/xtask/src/lint/mod.rs
• hub-client/src/App.tsx
• hub-client/src/components/Editor.tsx
• hub-client/src/components/ReplayDrawer.css
• hub-client/src/components/ReplayDrawer.test.tsx
• hub-client/src/components/ReplayDrawer.tsx
• hub-client/src/services/automergeSync.ts
• ts-packages/quarto-sync-client/src/client.ts

Purpose and Scope

The Quarto Rust monorepo (q2) is a next-generation implementation of Quarto that combines high-performance document processing with real-time collaborative editing. This repository aims to replace parts of the TypeScript/Deno runtime with a unified Rust implementation to enable shared validation logic, improved performance for Language Server Protocol (LSP) operations, and single-binary distribution README.md1-12

The project encompasses:

• Document processing infrastructure: A Rust port of Pandoc (the pampa crate) that parses Quarto Markdown (QMD) using Tree-sitter and produces Pandoc AST with full source location tracking README.md29-34
• Collaborative editing system: A browser-based editor (hub-client) with CRDT-based synchronization using Automerge, enabling real-time collaboration Cargo.toml147-148
• WASM compilation pipeline: Rust document processing code compiled to WebAssembly for client-side execution in browsers README.md22-24
• Precise Source Tracking: A core design principle where every semantic entity carries SourceInfo through all transformations for accurate error reporting README.md62-69
• History and Replay: A sophisticated document history system (ReplayDrawer) that allows users to navigate and restore previous versions of collaborative documents hub-client/src/components/ReplayDrawer.tsx42-148

For detailed information about specific subsystems, see:

• Repository Structure
• Key Concepts
• Architecture Diagrams

Sources: README.md1-69 Cargo.toml1-152 hub-client/src/components/ReplayDrawer.tsx42-148

Repository Organization

The repository is organized as a Cargo workspace for Rust crates and utilizes npm for TypeScript packages. WASM crates are excluded from the default workspace to avoid native dependency conflicts and specialized build requirements Cargo.toml8-12

Workspace Structure Diagram

Title: q2 Workspace Organization

Workspace Categories

Category	Major Crates	Role
Binaries	pampa, quarto-hub	CLI tools and the collaboration server Cargo.toml147-148
Core	quarto-core, quarto-source-map	Rendering orchestration and unified location tracking README.md53-55
Document	quarto-pandoc-types	Pandoc AST type definitions and serialization README.md59-61
Parsing	tree-sitter-qmd, quarto-yaml	Incremental Markdown and YAML parsing README.md56-57
WASM	wasm-qmd-parser	Browser-side parsing and rendering bindings Cargo.toml86-87

For a full list of crates and directory roles, see Repository Structure.

Sources: Cargo.toml1-152 README.md49-61

System Architecture

The system architecture bridges the gap between traditional static site generation and dynamic collaborative editing.

Data Flow Diagram

Title: QMD Processing and Collaboration Flow

Key Architectural Layers

1. Parsing Layer: Uses Tree-sitter for incremental, error-tolerant parsing of Markdown and embedded metadata README.md44-47
2. Transformation Layer: Converts syntax trees into a typed Pandoc AST. The quarto-ast-reconcile crate allows for reconciliation to align original and modified ASTs Cargo.toml126-127
3. Rendering Layer: A pipeline-based approach in quarto-core that handles template injection and SASS compilation Cargo.toml93-94 Cargo.toml114-115
4. Collaboration Layer: Synchronizes AST and text changes across clients using Automerge CRDTs. The quarto-sync-client manages DocHandle instances and WebSocket communication ts-packages/quarto-sync-client/src/client.ts9-38

For detailed diagrams of these interactions, see Architecture Diagrams.

Sources: README.md27-48 ts-packages/quarto-sync-client/src/client.ts9-38 Cargo.toml126-148

Core Technologies

• Rust & WebAssembly: The core logic is written in Rust, targeting both native execution and wasm32-unknown-unknown for browser-based tools README.md13-26
• Tree-sitter: Provides the foundation for the tree-sitter-qmd grammar, enabling fast, incremental parsing Cargo.toml77-81
• Pandoc AST: The system maintains high compatibility with the Pandoc AST, allowing for the use of Pandoc filters and templates README.md59-61
• Automerge: A JSON-like CRDT used for robust, conflict-free collaborative editing Cargo.lock179-182
• Ariadne: Used for visually clear, precise diagnostics that point to exact source locations README.md80-95
• Monaco Editor: Integrated into the hub-client to provide a VS Code-like editing experience with real-time presence indicators hub-client/src/components/Editor.tsx164-171

Sources: README.md13-95 Cargo.toml77-81 Cargo.lock179-182 hub-client/src/components/Editor.tsx164-171

Build and Development

The repository includes an xtask system for project-specific automation and a plan-driven development workflow managed via beads CLAUDE.md23-57

Tool / Command	Function
cargo xtask verify	Full CI-mirror: lints, builds, and tests the entire workspace including WASM and TS README.md103-104
br (Beads)	Issue tracking and task management integrated with the codebase CLAUDE.md52-57
cargo nextest	Recommended test runner for the workspace CLAUDE.md32
insta	Snapshot testing framework used extensively for AST and rendering verification Cargo.toml29

For more on the build system and TDD workflow, see Repository Structure.

Sources: README.md103-108 CLAUDE.md23-57 Cargo.toml29