README

Support for Markdown language in Nette framework and templating system Latte.

Requirements

• PHP >= 8.5
• Nette >= 3.2
• Latte >= 3.1

Installation

The best way to install interitty/markdown is using Composer:

composer require interitty/markdown

This package has no direct dependency on one particular implementation of the Markdown parser. It allows work uniformly with different libraries using dedicated adapters. When the selected option is no longer suitable or available for the current version of PHP, select another suitable option in the configuration.

The following composer packages are currently supported. It is possible to choose and install one or more at the same time.

composer require league/commonmark
composer require michelf/php-markdown

Then register the extension in the Nette config file:

# app/config/config.neon
extensions:
    markdown: Interitty\Markdown\Nette\DI\MarkdownExtension

Usage

A filter and tag can be used in any Latte template:

Inline support

HTML templates and mocks for web applications often come with a pre-formatted document to which translations need to be added. This is done by default using the {_...} notation. Minor corrections are then made over time in the form of text changes and highlighting. For these purposes, it is useful to provide limited markdown language support to allow this without the need to change the application code using the md filter or tag.

<p>{_'**Markdown** text content'|md}</p>

This function can of course also be used without the need for translations.

<p>{md '**Markdown** text content'}</p>

By default, the following HTML tags are supported in "inline" mode: a, abbr, b, br, cite, code, command, del, dfn, em, i, ins, kbd, mark, meter, progress, q, s, samp, small, span, strong, sub, sup, time, u, var, wbr. All others are removed from the resulting string. The list of allowed HTML tags can be changed in the allowedTagsInline configuration item.

# app/config/config.neon
markdown:
    allowedTagsInline: [b, i, u]

Block support

Sometimes you need to convert the whole markdown document without any restrictions. For this purpose, there is a "block" mode with its mdb filter and tag helper.

{block|mdb}
## Headline

**Markdown** text content
{/block}

{capture $markdownText}
## Headline

**Markdown** text content
{/capture}

{md $markdownText}

Standalone usage

Sometimes it can be useful to convert markdown text on its own without using the templating system. This can be done using the Interitty\Markdown\Markdown object obtained from the dependency injection container.

<?php

declare(strict_types=1);

namespace App\Models;

use Interitty\Markdown\Markdown;

class FooService
{
    public function __construct(
        protected Markdown $markdown
    ) {
    }

    public function processMarkdown(string $markdown): string
    {
        return $this->markdown->processMarkdown($markdown);
    }
}

Configuration

The extension is designed so that nothing more needs to be set by default. The currently installed parser is used as a latte filter md. However, it may be useful to use it under a different identifier, with a different service, or with the support for just a strict markdown.

# app/config/config.neon
markdown:
    adapter: null # Can be one of `commonMark`, `githubFlavoured`, `markdown`, `markdownExtra`, `texy` or one of `@service`
    allowedTagsInline: null # Or array of strings with allowed HTML tags for "inline" filter and tag.
    extended: true # false for strict markdown syntax only
    helper: `mdb` # Any string like `parsedown` to be compatible with previous markdown support implementation
    helperInline: `md` # Any string

Events

The markdown service also contains events that can modify the text input and output during processing. This can be useful, for example, for additional typographic editing that is not directly supported by the Markdown adapter itself.

The available events are onBeforeProcess, onAfterProcess and onAfterInlineProcess.

extensions:
    markdown: Interitty\Markdown\Nette\DI\MarkdownExtension

services:
    markdown.markdown:
        class: Interitty\Markdown\Markdown
        setup:
            - $onAfterProcess:
                - strtolower