Rst Laravel Package

Getting Started

Install via Composer: composer require gregwar/rst. Start with the core flow: instantiate Parser, parse your RST string, then render to HTML:

use Gregwar\RST\Parser;

$rst = "**Hello**\n\nThis is a *paragraph*.";
$html = (new Parser())->parse($rst)->render();
// <p><strong>Hello</strong></p>\n<p>This is a <em>paragraph</em>.</p>

First use case: convert a static .rst file (e.g., docs/CHANGELOG.rst) into an HTML fragment for a Laravel view. Check the repo’s examples/ folder—01_basic.php is the canonical starting point.

Implementation Patterns

• Documentation Pipeline Integration: Pre-render .rst content during deploy (e.g., via a Laravel Artisan command) and cache the HTML in the database or filesystem. Great for changelogs, READMEs, or Sphinx-generated docs.
• Admin/RST CMS: Allow content authors to write in RST (common in technical teams); parse at save-time using a custom RstRenderer service, storing raw RST + rendered HTML. Use Laravel’s caching for performance.
• AST Manipulation: Extend the parser to inject route-aware links or section anchors. Create a custom NodeVisitor to traverse the AST, then register it with Parser::setNodeVisitor($visitor).
• Blade Helpers: Wrap rendering in a Blade macro:

  Blade::directive('rst', fn ($expression) => "<?php echo app(App\\Services\\RstRenderer::class)->render($expression); ?>");
  

Gotchas and Tips

• Directive defaults: Out-of-the-box, Parser ignores unknown directives (e.g., .. important::). During development, enable strict mode (new Parser(true)) to surface unexpected syntax—otherwise errors vanish silently.
• Custom directives require manual registration: Define a class implementing DirectiveInterface, then call Parser::setDirective('mydirective', $instance). This replaces the previous directive, so avoid overwriting built-ins unintentionally.
• Whitespace = fragility: RST’s indentation rules are strict. A misaligned list item breaks parsing without throwing exceptions. Use Parser::setErrorHandler(fn ($msg) => logger()->warning('RST parsing: ' . $msg)) to catch subtle layout issues.
• No highlighter built-in: Code blocks render as <pre><code>...</code></pre> with no language tokenization. Add syntax highlighting post-render via JavaScript (e.g., Highlight.js) or a post-processing step (e.g., symfony/dom-crawler + php-highlighter).
• AST properties aren’t stable: Don’t access $node->children or $node->value directly across versions. Prefer NodeVisitor pattern for traversal—Laravel’s cache keys can store serialized ASTs safely, but validate format changes on package upgrades.