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

crst

A reStructuredText (RST) parser for Crystal that converts RST markup to HTML, XML (DocBook), and plain text.

Documentation

API documentation is available at: https://renich.gitlab.io/crst/

Installation

1. Add the dependency to your shard.yml:

   dependencies:
     crst:
       gitlab: renich/crst

2. Run shards install

Usage

Basic Usage

require "crst"

# Parse RST to AST
doc = Crst.parse("Hello World\n===========\n\nThis is a paragraph.")

# Convert to HTML
html = Crst.to_html("Hello World\n===========\n\nThis is a paragraph.")
puts html  # <div><h1>Hello World</h1><p>This is a paragraph.</p></div>

# Convert to XML (DocBook)
xml = Crst.to_xml("Hello World\n===========\n\nThis is a paragraph.")

# Convert to plain text
text = Crst.to_text("Hello World\n===========\n\nThis is a paragraph.")

Advanced Usage with Configuration

require "crst"

# Create custom configuration
config = Crst::Config.new
config.roles["highlight"] = "bg-yellow"  # Custom role styling

# Register custom directive
config.custom_directives["mydir"] = ->(name : String, args : Array(String), opts : Hash(String, String), children : Array(Crst::Node), cfg : Crst::Config) {
  # Custom directive implementation
  [Crst::Paragraph.new("Custom: #{args.join(' ')}")]
}

# Parse with configuration
rst_content = <<-RST
Custom Role
===========

This text has :highlight:`highlighted content`.

.. mydir:: argument1 argument2

   Custom directive content.
RST

html = Crst.to_html(rst_content, config)

API Reference

Core Methods

• Crst.parse(input : String, config : Config = Config.new) : Document - Parse RST text into AST
• Crst.to_html(input : String, config : Config = Config.new) : String - Convert to HTML
• Crst.to_xml(input : String, config : Config = Config.new) : String - Convert to DocBook XML
• Crst.to_latex(input : String, config : Config = Config.new) : String - Convert to LaTeX
• Crst.to_text(input : String, config : Config = Config.new) : String - Convert to plain text

Configuration

The Crst::Config class allows customization:

config = Crst::Config.new
config.tab_width = 4                    # Tab width for indentation
config.language = "crystal"             # Default language for code blocks
config.roles["custom"] = "css-class"    # Custom role definitions
config.custom_directives["name"] = proc # Custom directive handlers

Examples

Basic RST Document

My Document Title
=================

Introduction paragraph with *emphasis* and **strong** text.

Section Header
--------------

* Bullet list item 1
* Bullet list item 2

#. Numbered list item 1
#. Numbered list item 2

Code Example::

    def hello
      puts "Hello, World!"
    end

.. note::

   This is an admonition note.

Advanced Features

Hyperlinks and References:

Link to `external site <https://example.com>`_.
Reference to `internal target`_.

.. _internal target: https://internal.com

Tables:

+-------+-------+-------+
| Header| Header| Header|
+=======+=======+=======+
| Cell  | Cell  | Cell  |
+-------+-------+-------+

Footnotes and Citations:

Text with footnote [1]_ and citation [Smith2023]_.

.. [1] Footnote content here.
.. [Smith2023] Smith, J. (2023). Title of work.

Custom Roles and Directives:

Text with :custom:`custom role`.

.. figure:: diagram.png

   Figure caption text.

See docs/examples/ for comprehensive examples demonstrating various RST features.

API Documentation

Generated API documentation is available in the docs/technical/api/ directory after running make docs.

Development

• make build - Build in development mode
• make release - Build for production
• make spec - Run tests
• make docs - Generate documentation
• make format - Format code
• make lint - Run linter

Setup

To set up pre-push hooks for automatic testing and linting:

cp hooks/pre-push .git/hooks/
chmod +x .git/hooks/pre-push

This ensures code quality before pushing.

Supported RST Features

Structure

• Documents and sections with hierarchical headings
• Paragraphs with proper text flow
• Comments (ignored in output)

Lists

• Unordered (bullet) lists with -, *, +
• Ordered (numbered) lists with 1., 2., etc.
• Nested lists with proper indentation
• Definition lists (field lists)

Inline Markup

• Emphasis (italics)
• Strong emphasis (bold)
• Inline code literals
• interpreted text with custom roles
• Automatic hyperlink recognition
• Named and anonymous hyperlink references
• Inline hyperlink targets

Blocks

• Literal code blocks with :: syntax
• Doctest blocks (>>> prompts)
• Block quotes with indentation
• Line blocks with | syntax

Tables

• Simple tables with column separators
• Grid tables with +---+ borders
• Table headers and body separation

References

• Footnote references [1]_
• Citation references [Author2023]_
• Internal hyperlink targets
• External URI and email links

Directives

• Built-in directives:
  • .. code-block:: language - Syntax-highlighted code
  • .. math:: - Mathematical expressions
  • .. raw:: - Raw output content
  • .. figure:: uri - Images with captions
  • .. include:: file - File inclusion (safe)
  • .. note::, .. warning::, etc. - Admonitions
• Custom directive support via configuration
• Directive options and content blocks

Roles

• Built-in roles: :code:, :emphasis:, :strong:
• Custom role definitions via configuration
• Interpreted text processing

Output Formats

• HTML5 with semantic markup
• DocBook XML for technical publishing
• LaTeX for PDF generation
• Plain text for simple processing

Advanced Features

• Backslash escaping for special characters
• System messages for parsing errors
• Configurable tab width and language defaults
• Extensible architecture for custom extensions

Contributing

Please read CONTRIBUTING.rst for details on our code of conduct, and the process for submitting pull requests to us.

Contributors

• Rénich Bon Ćirić - creator and maintainer
• Gemini AI renich+gemini@woralelandia.com - co-developer

🛡️ Code of Honor

This project adheres to the Universal Code of Honor. By participating, you are expected to uphold this code.