gitlab.com/renich/crst

RST parser for Crystal

1 stars

4 dependents

License: AGPL-3.0

Installation

# Add this to your shard.yml
dependencies:
  crst:
    gitlab: renich/crst
    version: ~> 1.4.6

Then run:

shards install

shard.yml

Crystal

1.20.1

License

AGPL-3.0

Authors

Rénich Bon Ćirić, Gemini, Kimi

Target

ameba from lib/ameba/bin/ameba.cr

Dependencies

Development Dependencies

ameba*github: crystal-ameba/ameba, branch: masterdev

README

This README is the one indexed from the repository at its latest ref, not from the tag for this version.

📜 crst

Native Crystal reStructuredText (RST) parser and multi-format document compiler.

⚡ Highlights

Pure Native Crystal: Zero external C bindings or Python/Docutils runtime dependencies.
Rich Syntax Support: Sections, bullet/enumerated/definition/field/option lists, tables (simple and grid), literal blocks, doctests, and directives.
Exact AST Source Spans: Full 1:1 line and column coordinate tracking (line, column, end_line, end_column) on all AST nodes.
Multi-Target Rendering: High-speed compilation to HTML5, DocBook XML, LaTeX, and Plain Text.
Extensible Architecture: Typed custom interpreted roles and custom block directive Procs.

🚀 Quickstart

1. Installation

Add crst to your shard.yml:

dependencies:
  crst:
    gitlab: renich/crst
    version: ~> 1.5.1

Run shards install.

2. Basic Usage

require "crst"

rst_source = <<-RST
Sample Heading
==============

This is a paragraph with **strong** and *emphasis* formatting.

- First item
- Second item
RST

# 1. Parse directly to typed Abstract Syntax Tree (AST)
doc = Crst.parse(rst_source)

# 2. Render directly to HTML5, XML, LaTeX, or Plain Text
html = Crst.to_html(rst_source)
xml  = Crst.to_xml(rst_source)
tex  = Crst.to_latex(rst_source)
text = Crst.to_text(rst_source)

3. Custom Directives & Roles

require "crst"

config = Crst::Config.new
config.roles["badge"] = "badge-primary"

config.custom_directives["alert"] = ->(name : String, args : Array(String), opts : Hash(String, String), children : Array(Crst::Node), cfg : Crst::Config) {
  [Crst::Paragraph.new("ALERT: #{args.join(' ')}")] of Crst::Node
}

html = Crst.to_html(".. alert:: Notice!\n\nCheck :badge:`new` feature.", config)

📚 Documentation

Comprehensive guides and technical blueprints are located in docs/:

🛠️ Development

make spec   # Run test suite
make lint   # Run static analysis (Ameba, yamllint, rstcheck)
make docs   # Generate API documentation

🤝 Contributing & Code of Honor

Contributions are welcome! Please read CONTRIBUTING.rst for submission guidelines.

This project strictly adheres to the Universal Code of Honor.

💖 Support the Project

If you find crst valuable for your applications and toolchains, please consider supporting its development:

Sponsored and maintained by Rénich Bon Ćirić on Liberapay.

📄 License

This library is licensed under the AGPL-3.0 License.

crst