README

Laravel Blade adapter for fissible/transmark: a @transmark directive and <x-transmark> component render a Document (or a DOCX/Markdown file path) as HTML via HtmlWriter.

Requirements

• PHP ^8.2
• Laravel ^10.0, ^11.0, or ^12.0 (illuminate/support, illuminate/view, illuminate/contracts — no laravel/framework dependency)

Installation

composer require fissible/transmark-blade

The service provider (Fissible\Transmark\Blade\TransmarkBladeServiceProvider) is auto-discovered.

Usage

TransmarkRenderer::render() accepts either a Fissible\Transmark\Document you already have, or a .docx/.md/.markdown file path it reads and parses internally (dispatched by extension). Both the directive and the component accept the same union type.

Blade directive

@transmark($document)

{{-- or a file path --}}
@transmark('agreements/nda.docx')

Blade component

<x-transmark :document="$document" />

{{-- or a file path --}}
<x-transmark document="agreements/nda.docx" />

Important: never wrap @transmark(...) in {{ }} or {!! !!}

HtmlWriter (from fissible/transmark) already HTML-escapes text content (ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML5). Both the directive and the component output that already-escaped HTML directly, and neither needs (or accepts) extra raw-output syntax:

• Directive: use @transmark(...) bare. It is a Blade directive, not a {{ }}-style expression — its callback returns a complete <?php echo ...; ?> snippet that Blade splices in as-is. Wrapping it as {!! @transmark(...) !!} produces a nested <?php echo <?php echo ...; ?>; ?> parse error. Wrapping it as {{ @transmark(...) }} would additionally re-escape the HTML tags HtmlWriter generated (<p>, <strong>, etc.), breaking rendering even if it did compile.
• Component: <x-transmark> renders its own view with {!! $html !!} internally, so <x-transmark :document="$document" /> is always safe to use as-is.
• The {!! !!} vs. {{ }} distinction only applies if you skip both of the above and manually echo TransmarkRenderer::render()'s return value as a plain expression — see "Programmatic use" below.

Programmatic use (no Blade)

use Fissible\Transmark\Blade\TransmarkRenderer;

$html = TransmarkRenderer::render($document);       // Document object
$html = TransmarkRenderer::render('nda.docx');       // file path, dispatched by extension

If you echo $html in a Blade template yourself, use {!! $html !!}, not {{ $html }} — the latter would double-escape it.

Unsupported file extensions throw Fissible\Transmark\Blade\Exception\UnsupportedFormatException.

License

MIT