https://github.com/stormlightlabs/parserst
reStructuredText parser & renderer written in Rust
https://github.com/stormlightlabs/parserst
markdown recursive-descent-parser restructuredtext rst rust serde
Last synced: 2 months ago
JSON representation
reStructuredText parser & renderer written in Rust
- Host: GitHub
- URL: https://github.com/stormlightlabs/parserst
- Owner: stormlightlabs
- License: mit
- Created: 2025-10-25T06:00:46.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2025-10-25T06:12:08.000Z (3 months ago)
- Last Synced: 2025-10-25T08:15:19.789Z (3 months ago)
- Topics: markdown, recursive-descent-parser, restructuredtext, rst, rust, serde
- Language: Rust
- Homepage:
- Size: 43 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# parseRST
A lightweight, recursive-descent **reStructuredText parser** written in Rust.
## Overview
`parserst` is a small, fast, and self-contained parser for [reStructuredText](https://docutils.sourceforge.io/rst.html) 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](https://github.com/stormlightlabs/beacon)
## Features
| Category | Description |
| --------------------- | ------------------------------------------------------------------------------------------------ |
| **Inline parsing** | Supports `*emphasis*`, `**strong**`, `` `code` ``, and `` `link `_``. |
| **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, 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`:
```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
```rust
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:**
```html
Heading
This is emphasized, bold, and
inline code.
- Item 1
- Item 2
```
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
```bash
cargo test
```
Test with specific feature configurations:
```bash
# 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](https://github.com/casey/just) installed):
```bash
# View all recipes
just -l
```
## API Overview
| Function | Description |
| -------------------------- | ----------------------------------------------------------------------- |
| `parse(input: &str)` | Parses `.rst` text into a `Vec` 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](./LICENSE) or learn [more here](https://opensource.org/license/mit)
---
Made with ⚡️ by Stormlight Labs.
Stormlight Labs is just me, [Owais](https://github.com/desertthunder). Support my work on [Ko-fi](https://ko-fi.com/desertthunder).
[](https://brainmade.org)