Markdown Laravel Package

Getting Started

flarum/markdown is the Markdown formatting extension for Flarum (a PHP forum, not a Laravel app — it borrows Illuminate components but uses its own extender system). It wires s9e/text-formatter into Flarum's post rendering pipeline.

Minimal steps:

1. Check whether you already have it. This extension ships bundled with Flarum core. Run composer show flarum/markdown and php flarum extension:list first — most projects should not require it manually, and pulling a different version in can conflict with core.
2. If genuinely absent: composer require flarum/markdown (matching your core major version), then enable it:

   php flarum extension:enable flarum-markdown
   php flarum assets:publish
   php flarum cache:clear
   

3. Where to look first: extend.php (the extender array — this is Flarum's equivalent of a service provider), then js/src/forum/index.js for the composer/editor side.
4. First use case: render a post body server-side. Inject Flarum's Flarum\Formatter\Formatter and call parse($post->content) / render($xml) to get safe HTML out for emails, feeds, search indexes, or API payloads that don't go through the normal serializer.

Implementation Patterns

Server-side rendering (the bread-and-butter pattern). Flarum stores raw Markdown in posts.content and derives contentHtml through the Formatter. Whenever you need HTML outside the normal request cycle (queued notification emails, static exports, sitemap descriptions), resolve the formatter rather than calling Parsedown/CommonMark directly:

$formatter = resolve(\Flarum\Formatter\Formatter::class);
$xml  = $formatter->parse($post->content);   // cached parse tree
$html = $formatter->render($xml);            // safe HTML

Pass only $formatter->render() output to views — never htmlspecialchars-wrap it again or you'll get <em>.

Extending the syntax via extenders. Custom Markdown/BBCode is added through the Flarum\Extend\Formatter extender in your own extension's extend.php:

return [
    (new Flarum\Extend\Formatter)
        ->configure(function ($configurator) {
            $configurator->plugins->load('MyPlugin');
            $configurator->Litedown; // or BBCodes, MediaEmbed, etc.
        }),
];

Register tags/renderers there, or hook configurator.configure if you prefer event-listener style wiring over extenders.

Frontend integration. The forum side configures the same s9e runtime in JS. If you add a syntax on the server, mirror the tag registration in your extension's JS (js/src/forum/) so the live composer preview matches the final render. The extension bundles the composer toolbar and markdown-aware textarea behavior; extend rather than replace js/src/forum/index.js.

Workflows worth knowing:

• Adding a syntax only affects future renders; existing posts get the new behavior automatically on next render since only raw content is stored. No data migration needed.
• For bulk operations (re-indexing, exports), loop parse/render but be aware of the formatter's internal cache keys — clear with php flarum cache:clear after changing formatter config.
• Test formatter changes with a handful of real posts before enabling the extension in production; php flarum + the extension's PHPUnit suite is the fastest loop.

Gotchas and Tips

• Not a Laravel package. There's no MarkdownServiceProvider in the Laravel sense; registration is entirely via extend.php return arrays of extenders, and the JS half is a separate build. Don't look for config/markdown.php.
• Version drift bites. Because it's bundled with core, manually requiring a version that doesn't match your Flarum major version breaks the formatter's JS/PHP contract. Let core constrain it unless you have a specific reason.
• Raw HTML is intentionally restricted. By default users can't inject arbitrary tags like <div> or <iframe>. Don't "fix" this with a custom configure() block that enables unsafe HTML unless you're also auditing the output — the security model assumes the default.
• Cache invalidation for config changes. After editing the extender's formatter config you must run php flarum cache:clear; after JS changes you must rebuild assets (php flarum assets:publish), otherwise the composer preview and server render disagree and users file "my formatting is broken" reports.
• Parse errors are runtime exceptions. Unclosed tags or bad plugin config surface as RuntimeException from s9e. Wrap one-off batch scripts in try/catch and log the offending $post->id rather than dying mid-loop.
• Shortcodes and mentions are separate extensions. @mention, :emoji:, and media embedding are handled by flarum/mentions, flarum/emoji, flarum/mediaembed — if syntax "doesn't work" on a server-rendered email, check whether those extensions are enabled in the same context that's doing the render.
• Debugging tip: $formatter->parse() yields XML; inspect that intermediate tree before blaming your renderer. It's the fastest way to tell whether a plugin failed to register or merely failed to render.
• Extension points: Flarum\Extend\Formatter::configure() is the sanctioned hook; for anything more invasive fall back to the underlying s9e configurator events (configurator.configure), but prefer the extender so your customization composes cleanly with other extensions.