semmelsamu/commonmark-extensions

Custom Markdown extensions for CommonMark PHP

0.1.0 2025-03-23 23:41 UTC

Requires

• league/commonmark: ^2.6
• scrivo/highlight.php: ^9.18

Requires (Dev)

• phpunit/phpunit: ^12.0

MIT

• Samuel Kroiß

README

Custom extensions for the CommonMark PHP Markdown parser. Extensions contained:

• Callout - Renders obsidian-like callout and github-like alarm blockquotes
• CodeHighlighting - Highlights code blocks using highlight.php
• LaTex - Escapes inline- and block-level latex code between dollar signs ($)
• Wikilink - Processes Wikilinks like in Obsidian
• WikilinkEmbed - Embeds Wikilinks prefixed with a !

Installation

TODO: Upload to Packagist

Setup

use League\CommonMark\Environment\Environment;

// Create the converter environment:
$environment = new Environment($config);

// Add the extensions you wish:
$environment->addExtension(new CommonmarkExtension());

// Go forth and convert you some Markdown!
$converter = new MarkdownConverter($environment);

Usage

Callout

use Semmelsamu\CommonmarkExtensions\Callout\CalloutExtension;

You may want to configure the extension:

$config = [
    "callout" => [
        "render_icon" => fn(string) => string;
    ],
    // other configuration ...
]

• render_icon - A closure expecting the callout type and returning valid HTML which will be rendered as the icon of the callout.

CodeHighlighting

use Semmelsamu\CommonmarkExtensions\CodeHighlighting\CodeHighlightingExtension;

You may want to download one of the various highlight.js themes in order to actually see any code highlighting, as this extension does not apply any colors to the code by itself, it only applies CSS classes. Download the css files here and load them in your HTML.

LaTex

use Semmelsamu\CommonmarkExtensions\LaTex\LaTexExtension;

You may want to download a LaTex highlighting engine like MathJax, as this extension does not render LaTex, but escapes it. Use the code below to load MathJax into your HTML:

<script>
    MathJax = {
        tex: {
            inlineMath: [
                ["$", "$"],
                ["\\(", "\\)"],
            ],
            displayMath: [["$$", "$$"]],
        },
        options: {
            enableMenu: false,
        },
    };
</script>
<script
    id="MathJax-script"
    async
    src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"
></script>

Wikilink

use Semmelsamu\CommonmarkExtensions\Wikilink\WikilinkExtension;

You may want to configure the extension:

$config = [
    'wikilink' => [
        'resolve' => fn (string) => string
    ]
]

• resolve - A closure expecting the wikilink text and returning the resolved href value which will be used in the <a> tag.

WikilinkEmbed

use Semmelsamu\CommonmarkExtensions\WikilinkEmbed\WikilinkEmbedExtension;

You may want to configure the extension:

$config = [
    'wikilink_embed' => [
        'resolve' => fn(string) => string,
        'renderers' => [
            fn (string, ?string) => string,
            // ...
        ]
    ]
];

• resolve - A closure expecting the wikilink text and returning the resolved href value which will be used in the <a> tag.
• renderers - An array consisting of closures expecting the wikilink and a possible caption and returning valid HTML which will be rendered as the wikilink content.

Testing

./vendor/bin/phpunit --do-not-cache-result

License

This project is licenced under the MIT license. See the LICENSE file for more information.