A highly configurable markdown renderer and Blade component for Laravel

Overview

A highly configurable markdown renderer and Blade component for Laravel

Latest Version on Packagist GitHub Tests Action Status GitHub Code Style Action Status Total Downloads

This package contains:

  • a Blade component that can render markdown
  • a highly configurable class that you can use to render markdown

Let's start with an example of the provided x-markdown Blade component. This chunk of markdown...

<x-markdown>
# My title

This is a [link to our website](https://spatie.be)

```php
echo 'Hello world';
```
x-markdown>

... will be converted by to component to this chunk of HTML:

My title

This is a link to our website

echo 'Hello world';
">
<div>
    <h1 id="my-title">My titleh1>
    <p>This is a <a href="https://spatie.be">link to our websitea>p>
    <pre class="shiki" style="background-color: #fff"><code><span class="line"><span
        style="color: #005CC5">echospan><span style="color: #24292E"> span><span style="color: #032F62">'Hello world'span><span
        style="color: #24292E">;span>span>
<span class="line">span>code>pre>
div>

You can also programmatically render HTML.

// by resolving the class out of the container all the options
// in the config file will be used.

app(Spatie\LaravelMarkdown\MarkdownRenderer::class)->toHtml($markdown);

Out of the box, the x-markdown component and MarkdownRenderer can:

  • highlight code blocks correctly (via Shiki PHP) for 100+ languages, including PHP, JS, Blade, and many more.
  • add anchor links to headings
  • cache results to increase performance

Support us

We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products.

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall.

Documentation

You can find installation instructions and detailed instructions on how to use this package at the dedicated documentation site.

Related packages

If you only need the league/commonmark extension to highlight code, head over to spatie/commonmark-shiki-highlighter.

In case you don't need the markdown support, but want to highlight code directly, take a look at spatie/shiki-php.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

Alternatives

If you don't want to install and handle Shiki yourself, take a look at Torchlight, which can highlight your code with minimal setup.

License

The MIT License (MIT). Please see License File for more information.

Comments
  • Set secure defaults for html escaping

    Set secure defaults for html escaping

    User-supplied content needs to be passed into the blade component unescaped, otherwise blockquotes which use > will not work correctly. This PR aims to set secure defaults that prevent reflected XSS attacks.

    opened by fkellner 4
  • Allow priority to be set for Block and Inline Renderers

    Allow priority to be set for Block and Inline Renderers

    Hi,

    I noticed when trying to add a custom renderer that there was no way to pass a priority option through (meaning that if a renderer for the element type had already been registered and returned a non-null result, the renderer added to the config wouldn't be used).

    This PR allows a priority key to be set for block / inline renderers, but falls back to 0 if not found. (0 is the default priority, so without adding the new key nothing should change),

    I have also updated the comments in the config file to have the correct array key (class instead of blockClass) and bought the installation setup documentation page to be inline with the config file (as many of the comments were already out of date before I made my own changes to the config file).

    As an complete aside, locally I went to run the tests just to be sure nothing I changed caused any issues, but I was getting a number of failures even when I reverted my changes and I'm really not sure why.

    opened by SimonJulian 3
  • Use spatie/commonmark-shiki-highlighter 2.0

    Use spatie/commonmark-shiki-highlighter 2.0

    This update accounts for changes made in the spatie/commonmark-shiki-highlighter as well as those further upstream in League\CommonMark 2.0 as that had some significant ones. The other change this accounts for is that Shiki upstream changed color schemes to keep current with their sources too.

    opened by mallardduck 2
  • Adding inline parsers

    Adding inline parsers

    The inline parsers are very useful.

    For example if one wanted to add a hashtag system, or a "mention" system using match for @somename like here in github, they could make an inline parser as in the example on commonmark: https://commonmark.thephpleague.com/2.3/customization/inline-parsing/#inline-parser-examples

    This pr simply adds the option to the config

    opened by MortenDHansen 1
  • Add information about using NVM in development

    Add information about using NVM in development

    Hello!

    I recently made a PR in shiki php repo to add docs around using Node Version Manager.

    I have made a similar PR here to update the documentation to provide some information to people using NVM to hopefully help them avoid the issues I had with not understanding why it was not working properly.

    Thanks :)

    opened by Drewdan 1
  • Side note for using blade's unescaped statememt

    Side note for using blade's unescaped statememt

    This caught me off guard (Shouldn't have, but I'm tired!). I thought it would be worth a little footnote. If you use default blade statement:

    {{ $article->markdown }}
    

    The markdown is passed through PHP's htmlspecialchars function and all the HTML specific tags < > ' etc are replaced with their ASCII equivalent. To stop this (And for your lovely package to work) a user would need to use the unescaped, effectively raw blade statement:

    {!! $article->markdown !!}
    
    opened by AshboDev 1
  • Add tests to identify and fix bug with renderers priority

    Add tests to identify and fix bug with renderers priority

    Per title, this PR creates a test that identifies a bug and fixes said bug.

    Up until commit https://github.com/spatie/laravel-markdown/pull/26/commits/3154c0dba645522a61f51176d654013e6888d9d5 the PR has intentioally failing builds. However at commit https://github.com/spatie/laravel-markdown/pull/26/commits/2da77b7253cc05f9a486d592d941450d7a0d0487 the underlying bug was fixed and the subsequent PR adds a method parameter to bring the addBlockRenderer and addInlineRenderer methods in parity with the new funtionality.

    opened by mallardduck 1
  • Corrected some markdown, spelling, and URL mistakes...

    Corrected some markdown, spelling, and URL mistakes...

    Saw one of @freekmurze 's tweets referring to this (newer) package, which I'd not yet heard of, so I took a look. I just noticed a few links that weren't working, so came in to make a couple corrections. I haven't tested the links, but just made what I assume are the right changes. 😜

    Please let me know if there are any questions/concerns.

    Thanks again for your work...! 🚀

    opened by telkins 1
  • Enable use of RenderedContentInterface and small fix

    Enable use of RenderedContentInterface and small fix

    hey @freekmurze - this change makes a quick fix for the 2.0 release related to extensions to help ensure things work properly. There were parts of the initial changes I made that were not covered by tests to catch the logic issue.

    Quickfix

    Make sure extensions can be given as class names (strings) or instances. So i've made adjustments to ensure extension load properly.

    Specifically these lines would be affected: https://github.com/spatie/laravel-markdown/blob/991ff79926e3eb6667ed0c2e6793a63825516cf6/src/MarkdownRenderer.php#L149 https://github.com/spatie/laravel-markdown/blob/991ff79926e3eb6667ed0c2e6793a63825516cf6/src/MarkdownRenderer.php#L78

    New feature

    This also adds a method that mimics the league convertToHtml method for users. Adding this method and covering it with tests was what caused me to encounter the error to begin with. Otherwise I would have opted to split them up.

    This addition is important for users that want the FrontMatterExtension (or similar). Since these shouldn't return a string directly like existing methods do. So the new method returns a RenderedContentInterface object specific to the renderer. For instance, they can use any potential extension specific results. Like:

    $result = app(\Spatie\LaravelMarkdown\MarkdownRenderer::class)->renderMarkdown($markdown);
    
    // Grab the front matter:
    if ($result instanceof RenderedContentWithFrontMatter) {
        $frontMatter = $result->getFrontMatter();
    }
    
    opened by mallardduck 1
  • Don't ignore extensions in the Blade component

    Don't ignore extensions in the Blade component

    • [x] Added the omitted line of code.
    • [x] Fixed tests that weren't running properly with testbench.
    • [x] Add tests covering extensions (both the renderer and the component).

    Details here: #14

    opened by benjamincrozat 1
  • Fix disregard of `commonmarkOptions` parameter

    Fix disregard of `commonmarkOptions` parameter

    without this change, the commonmarkOptions parameter documented here has no effect. I assumed that all options on this page should be exposed and updated the example accordingly.

    opened by fkellner 1
Releases(2.2.4)
  • 2.2.4(May 21, 2022)

    What's Changed

    • MarkdownBladeComponent missing inline parsers by @MortenDHansen in https://github.com/spatie/laravel-markdown/pull/37

    Full Changelog: https://github.com/spatie/laravel-markdown/compare/2.2.3...2.2.4

    Source code(tar.gz)
    Source code(zip)
  • 2.2.3(May 11, 2022)

    What's Changed

    • Adding inline parsers by @MortenDHansen in https://github.com/spatie/laravel-markdown/pull/36

    New Contributors

    • @MortenDHansen made their first contribution in https://github.com/spatie/laravel-markdown/pull/36

    Full Changelog: https://github.com/spatie/laravel-markdown/compare/2.2.2...2.2.3

    Source code(tar.gz)
    Source code(zip)
  • 2.2.2(Mar 8, 2022)

    What's Changed

    • Update .gitattributes by @erikn69 in https://github.com/spatie/laravel-markdown/pull/34
    • Use afterResolving on markdown component register by @erikn69 in https://github.com/spatie/laravel-markdown/pull/35

    New Contributors

    • @erikn69 made their first contribution in https://github.com/spatie/laravel-markdown/pull/34

    Full Changelog: https://github.com/spatie/laravel-markdown/compare/2.2.1...2.2.2

    Source code(tar.gz)
    Source code(zip)
  • 2.2.1(Feb 28, 2022)

  • 2.2.0(Jan 13, 2022)

    What's Changed

    • Add support for Laravel 9
    • Fix broken link in code highlighting documentation by @AshboDev in https://github.com/spatie/laravel-markdown/pull/27
    • Side note for using blade's unescaped statememt by @AshboDev in https://github.com/spatie/laravel-markdown/pull/28

    New Contributors

    • @AshboDev made their first contribution in https://github.com/spatie/laravel-markdown/pull/27

    Full Changelog: https://github.com/spatie/laravel-markdown/compare/2.1.1...2.2.0

    Source code(tar.gz)
    Source code(zip)
  • 2.1.1(Dec 27, 2021)

    What's Changed

    • Add tests to identify and fix bug with renderers priority by @mallardduck in https://github.com/spatie/laravel-markdown/pull/26

    Full Changelog: https://github.com/spatie/laravel-markdown/compare/2.1.0...2.1.1

    Source code(tar.gz)
    Source code(zip)
  • 2.1.0(Dec 3, 2021)

    What's Changed

    • Corrected some markdown, spelling, and URL mistakes... by @telkins in https://github.com/spatie/laravel-markdown/pull/20
    • Allow priority to be set for Block and Inline Renderers by @SimonJulian in https://github.com/spatie/laravel-markdown/pull/23

    New Contributors

    • @telkins made their first contribution in https://github.com/spatie/laravel-markdown/pull/20
    • @SimonJulian made their first contribution in https://github.com/spatie/laravel-markdown/pull/23

    Full Changelog: https://github.com/spatie/laravel-markdown/compare/2.0.1...2.1.0

    Source code(tar.gz)
    Source code(zip)
  • 2.0.1(Sep 13, 2021)

  • 2.0.0(Sep 12, 2021)

  • 1.1.3(Aug 27, 2021)

  • 1.1.2(Aug 13, 2021)

  • 1.1.1(Jul 25, 2021)

  • 1.1.0(Jul 12, 2021)

  • 1.0.1(Jul 12, 2021)

  • 1.0.0(Jul 12, 2021)

  • 0.0.3(Jul 12, 2021)

  • 0.0.2(Jul 11, 2021)

  • 0.0.1(Jul 11, 2021)

Owner
Spatie
We create products and courses for the developer community
Spatie
Highly-extensible PHP Markdown parser which fully supports the CommonMark and GFM specs.

league/commonmark league/commonmark is a highly-extensible PHP Markdown parser created by Colin O'Dell which supports the full CommonMark spec and Git

The League of Extraordinary Packages 2.3k Sep 28, 2022
Easily add routes to your Laravel app by creating Markdown or Blade files

Laravel Pages This package lets you create pages using Markdown or Blade without having to worry about creating routes or controllers yourself. Essent

ARCHTECH 103 Sep 12, 2022
Generate pseudo-static pages from markdown and HTML files for Flarum

Flarum Pages Generator This is not a Flarum extension. This package provides a Flarum extender that you can use in the local extend.php to define cust

Clark Winkelmann 7 Feb 21, 2022
Symfony 5 bundle to easily create dynamic subpages with Markdown. Useful for help sections and wikis.

MarkdownWikiBundle This bundle allows you to create rich subpages in a Symfony project using Markdown. Pages are stored in a file cache and sourced fr

Gigadrive UG 3 Apr 26, 2022
A super lightweight Markdown parser for PHP projects and applications.

A speedy Markdown parser for PHP applications. This is a super lightweight Markdown parser for PHP projects and applications. It has a rather verbose

Ryan Chandler 13 May 31, 2022
Better Markdown Parser in PHP

Parsedown Better Markdown Parser in PHP - Demo. Features One File No Dependencies Super Fast Extensible GitHub flavored Tested in 5.3 to 7.3 Markdown

Emanuil Rusev 14.2k Sep 24, 2022
Convert HTML to Markdown with PHP

HTML To Markdown for PHP Library which converts HTML to Markdown for your sanity and convenience. Requires: PHP 7.2+ Lead Developer: @colinodell Origi

The League of Extraordinary Packages 1.5k Sep 28, 2022
A PHP tool to generate templateable markdown documentation from the docblocks or type-hints of your codebase.

Roster Installation To install, simply require the package using composer: composer require

Jordan LeDoux 14 Sep 11, 2022
Render colored Markdown contents on console terminal

cli-markdown Render colored markdown contents on console terminal Preview run demo by php example/demo.php Features support auto render color on termi

PHPComLab 5 Jan 27, 2022
PHP Markdown Engine Support

PHP Markdown Version v1.x support all PHP version >=5.4 v2.x support all PHP version >=7.0 Cài đặt thư viện Thư viện này được cài đặt thông qua Compos

Hung Nguyen 3 Jul 1, 2022
markdown wiki/blog

Kwiki markdown wiki/blog Usage Place your markdown files in the /wiki directory. Categories are directories and subcategories are subdirectories. If y

Ryan Winchester 77 May 29, 2022
Rendering markdown from PHP code

JBZoo / Markdown Installing composer require jbzoo/markdown Usage Rendering Table <?php declare(strict_types=1); use JBZoo\Markdown\Table; echo (new

JBZoo Toolbox 1 Dec 26, 2021
Gruik ! An open-source markdown note-taking web app. [ABANDONED PROJECT]

What is Gruik ? It's a free & open-source note-taking service. A space where you can store notes, tutorials, code snippets... by writing them in markd

Adrien Pétremann 331 Aug 25, 2022
PHP Markdown & Extra

PHP Markdown & Extra An updated and stripped version of the original PHP Markdown by Michel Fortin. Works quite well with PSR-0 autoloaders and is Com

dflydev 173 Jan 18, 2022
A simple regex-based Markdown parser in PHP

Slimdown A simple regex-based Markdown parser in PHP. Supports the following elements (and can be extended via Slimdown::add_rule()): Headers Links Bo

Aband*nthecar 14 Sep 5, 2022
Docbook Tool for static documentation generation from Markdown files

Roave Docbook Tool Static HTML and PDF generator tool for generating documentation from Markdown files. Generates a deployable HTML file from Markdown

Roave, LLC 30 Aug 1, 2022
PHP based Markdown documentation viewer

PHP based viewer for Markdown files, to view them with fenced code highlighting and navigation.

null 4 Sep 10, 2022
Pug Renderer - a (heavily based on the PhpRenderer) renderer for rendering Pug view scripts into a PSR-7 Response object

Pug Renderer This is a (heavily based on the PhpRenderer) renderer for rendering Pug view scripts into a PSR-7 Response object. It works well with Sli

Marcello Duarte 6 Oct 27, 2020
API Blueprint Renderer for Laravel, customizable via Blade templates

API Blueprint Renderer for Laravel This Laravel package Blueprint Docs renders your API Blueprint. It comes with a standard theme that you can customi

Michael Schmidt-Voigt 225 Sep 16, 2022
Parser for Markdown and Markdown Extra derived from the original Markdown.pl by John Gruber.

PHP Markdown PHP Markdown Lib 1.9.0 - 1 Dec 2019 by Michel Fortin https://michelf.ca/ based on Markdown by John Gruber https://daringfireball.net/ Int

Michel Fortin 3.3k Sep 24, 2022