parseRST

A lightweight, recursive-descent reStructuredText parser written in Rust.

Overview

parserst is a small, fast, and self-contained parser for reStructuredText documents. It aims to provide a clean, idiomatic Rust API for converting .rst content into structured AST nodes or HTML/Markdown.

This crate is ideal for:

• Building static site generators, documentation tools, or format converters.
• Integrating reStructuredText support into note-taking or content-processing apps.
• Experimenting with parsing techniques and markup language design.
• Parsing Python docstrings

Features

Category	Description
Inline parsing	Supports *emphasis*, **strong**, `code`, and `link <https://...>`_.
Block parsing	Detects headings, paragraphs, lists (ordered/unordered), code fences, and quote blocks.
Output	Render to HTML (always available) or Markdown (requires markdown feature).
Serialization	Serialize AST to JSON, YAML, or any serde-supported format (requires serde feature).
AST Access	Exposes a clean, typed AST (Block, Inline, Field, ListKind) for custom rendering.
Error Handling	Safe Result<Vec<Block>, ParseError> API with detailed line numbers.
Minimal deps	No external parser frameworks or macros; all features are optional and can be enabled as needed.

Installation

Add to your Cargo.toml:

[dependencies]
parserst = "0.1"

# With markdown support
parserst = { version = "0.1", features = ["markdown"] }

# With serde serialization support
parserst = { version = "0.1", features = ["serde"] }

# With all features
parserst = { version = "0.1", features = ["markdown", "serde"] }

Example

use parserst::html_of;

fn main() {
    let rst = r#"
Heading
=======

This is *emphasized*, **bold**, and ``inline code``.

- Item 1
- Item 2
"#;

    let html = html_of(rst);
    println!("{}", html);
}

Output:

<h1>Heading</h1>
<p>
    This is <em>emphasized</em>, <strong>bold</strong>, and
    <code>inline code</code>.
</p>
<ul>
    <li>Item 1</li>
    <li>Item 2</li>
</ul>

The AST can be serialized to any format supported by serde: JSON, YAML, TOML, MessagePack, etc.

Design

• Recursive Descent — every rule is expressed in idiomatic Rust, not macros.
• Predictable — prioritizes correctness over complete reStructuredText parity.
• Composabe — easy to extend or replace the renderer layer (e.g., to JSON, Markdown, or AST tools).
• No Unsafe — guaranteed safe Rust implementation.

Tests & Builds

cargo test

Test with specific feature configurations:

# Without any features
cargo test --no-default-features
cargo build --no-default-features # or cargo build

# With markdown
cargo test --features markdown
cargo build --features markdown

# With serde
cargo test --features serde
cargo build --features serde

# All features
cargo test --all-features
cargo build --release --all-features

Using just (if you have just installed):

# View all recipes
just -l

API Overview

Function	Description
parse(input: &str)	Parses .rst text into a Vec<Block> AST.
html_of(input: &str)	Parses and renders the input as HTML.
markdown_of(input: &str)	Parses and renders the input as Markdown (requires markdown feature).

Types

Item	Description
Block	Top-level AST nodes such as headings, paragraphs, directives, field lists, tables, etc.
Inline	Inline nodes nested inside Block variants (text, emphasis, strong, code, links)
Field	A field entry within a field list (e.g., :param x: description)
ListKind	Enum describing list flavor (Ordered or Unordered) for Block::List

License

See MIT License or learn more here

---

Made with ⚡️ by Stormlight Labs.

Stormlight Labs is just me, Owais. Support my work on Ko-fi.