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/:

• User Documentation:
  • Getting Started
  • Basic Usage
  • Configuration Guide
  • Advanced Features
  • Examples Overview
• Specifications & Blueprints:
  • Business Specification
  • Functional Specification
  • Technical Specification
  • API Specification
  • Project Roadmap
  • Architecture Design

---

🛠️ 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.