README

ALTO RST parses reStructuredText into the ROM, a source-positioned object model you can lint, format, edit, and convert to safe HTML, preserving everything you don't touch.

The core has no runtime Composer dependencies. It supports docutils RST, Sphinx syntax, and the conventions used by Symfony documentation. Trusted extensions can add directives, roles, lint rules, fixes, formatter passes, statistics, and conversion mappings.

The full guide set lives under docs/.

Need	Start with
Convert RST to safe HTML	`Rst::sphinx()->toHtml($source)`
Parse and inspect a document	`Rst::sphinx()->parse($source)`
Inspect targets and references	`$result->references()`
Lint a document	`Linter::lint()`
Fix, format, or edit source	`FixEngine`, `Formatter`, and `Editor`
Convert RST and Markdown	`RstToMarkdown` and `MarkdownToRst`
Convert a documentation directory	`ProjectConverter::convertDirectory()`
Add trusted behavior	`Profile::withExtension()`

Installation

Install ALTO RST with Composer:

composer require alto/rst

ALTO RST requires PHP 8.4 or later. No Python or Sphinx process is involved at runtime.

Quick Start

use Alto\Rst\Rst;

$source = "Run ``composer install``.\n";
$html = Rst::sphinx()->toHtml($source);

The result is:

<p>Run <code>composer install</code>.</p>

Direct rendering is the shortest path when HTML is the only result you need. Output is safe by default: text is escaped, unsafe URL schemes are filtered, and file-reading directives stay disabled.

Choose the narrowest profile that matches the source:

Rst::docutils();
Rst::sphinx();
Rst::symfony();

See Installation, Parsing, Rendering, and Security for setup, profile, and rendering policies.

Parse a document when you need more

Parsing keeps the document tree, original byte positions, references, and recovery problems available for later operations:

use Alto\Rst\Rst;

$source = <<<'RST'
    .. _installation:

    Installation
    ============

    Read the :ref:`installation` section.
    RST;

$result = Rst::sphinx()->parse($source);

$document = $result->document();
$parserProblems = $result->problems();
$references = $result->references();
$referenceProblems = $references->problems();

Malformed input recovers into typed parser problems instead of losing source text. Reference resolution has its own report, so syntax recovery and broken document links remain distinguishable.

The same parsed model powers linting, project-wide reference resolution, source-preserving edits, and conversion. Maintenance operations return exact patches before anything is saved. Project conversion discovers .rst files recursively, resolves cross-document Sphinx links, and aggregates every unsupported, lossy, or approximate mapping for review. Resolved footnotes, citations, and substitutions have explicit Markdown mappings, including collision-safe anchors across expanded include files. Code fence language names such as html+twig remain unchanged.

The documentation covers this in more depth: Linting to run and configure the recommended rules, Conversion to convert individual documents or complete projects between RST and Markdown, and Editing for conservative fixes, formatting, typed edits, diffs, and conflict-safe file persistence.

Extend

Trusted extensions add directives, roles, lint rules, fixes, formatter passes, statistics, and conversion mappings through compiled profile contracts. Read Extensions for the extension contracts and Reference for how local and project-wide targets, links, notes, citations, and substitutions resolve.

Documentation

Documentation index: browse the complete guide set.
Security: control URLs, raw HTML, includes, and other file-reading constructs.

Contributing

Contributions of all kinds are welcome. Visit the project on GitHub to report a bug, suggest a feature, or open a pull request.

Before submitting code, run:

# Runs PHP CS Fixer, PHPStan, and PHPUnit
composer qa

Changes to public behavior should include tests and documentation. Run composer coverage separately to enforce the 97% line-coverage floor.

The suite runs against a pinned docutils 0.23 fixture corpus committed to the repository. No Python or Sphinx process is involved, at runtime or at test time.

Set ALTO_RST_UX_CORPUS to a Symfony UX checkout to also run the corpus conversion tests; they skip when it is unset.

Support

ALTO RST is open source. You can support its continued development through GitHub Sponsors.

Sharing this package with others or starring it on GitHub is also much appreciated.

License

ALTO RST is released by ALTO PHP under the MIT License.

alto / rst

Maintainers

Package info

Fund package maintenance!

Statistics

Security