Packages · v2.x

Markdown

The Markdown package (src/packages/Markdown) parses Markdown (CommonMark + GitHub Flavored Markdown) into HTML without any dependency. It exposes a document API (title, description, summary, sections, links, images, code blocks) and converts HTML files and templates into Markdown.

Module

Manager NeoPHP\Package\Markdown\MarkdownManager (final)
Interface NeoPHP\Package\Markdown\MarkdownManagerInterface
Attribute #[Package(provider: MarkdownProvider::class)]
Requires nothing

Inject MarkdownManagerInterface in a service, a command or a controller:

use NeoPHP\Package\Markdown\MarkdownManagerInterface;

public function __construct(private MarkdownManagerInterface $markdown)
{
}

The module is enabled by default. To disable it in a project, add it to config/config.php (see the Kernel documentation):

NeoPHP\Package\Markdown\MarkdownManager::class => false,

The public API of the module is its manager and its interface, Contract\, the attributes, the exceptions, the events and the classes documented below. The classes marked @internal are used by the framework only.

Quick start

Inject NeoPHP\Package\Markdown\MarkdownManagerInterface (autowired, implemented by NeoPHP\Package\Markdown\MarkdownManager):

<?php

declare(strict_types=1);

namespace App\Controller;

use NeoPHP\Component\Controller\Contract\AbstractController;
use NeoPHP\Component\Http\Response\Response;
use NeoPHP\Package\Markdown\MarkdownManagerInterface;

class DocController extends AbstractController
{
    public function show(MarkdownManagerInterface $markdown): Response
    {
        $document = $markdown->get('docs/guide.md');

        return $this->render('doc/show.html.twig', [
            'title' => $document->getTitle(),
            'summary' => $document->getSummary(),
            'content' => $document->toHtml(),
        ]);
    }
}
$html = $markdown->toHtml('**Hello** world');
$markdown->parse('templates/page/about.html.twig', ['user' => $user])->to('docs/about.md');

Reading a Markdown file

Method Description
get(string $file): MarkdownDocument reads a .md file (absolute path or relative to the project root)
fromString(string $markdown): MarkdownDocument parses a Markdown string
toHtml(string $markdown): string converts a Markdown string into HTML (raw HTML kept: trusted content)
toSafeHtml(string $markdown): string converts untrusted Markdown into HTML (raw HTML escaped)

A missing file throws NeoPHP\Package\Markdown\Exception\MarkdownException.

MarkdownDocument

NeoPHP\Package\Markdown\Document\MarkdownDocument:

Method Description
getSource(): string the Markdown source
toHtml(): string the HTML (headings carry an id)
getTitle(): ?string text of the first level 1 heading
getDescription(): ?string first paragraph after the title, as plain text
getHeadings(): array Heading objects (getLevel(), getText(), getId(), getAnchor(), toArray())
getSummary(): array tree of headings: ['level', 'text', 'id', 'children' => [...]]
getSections(): array level 2 sections keyed by title
getSection(string $title): ?Section a section by title or id (case insensitive)
getLinks(): array ['text', 'url', 'title']
getImages(): array ['alt', 'url', 'title']
getCodeBlocks(): array ['language', 'code']

A Section gives getTitle(), getId(), getLevel(), getMarkdown() (content without the heading) and toHtml():

$changelog = $markdown->get('README.md')->getSection('Changelog')?->toHtml();

Ids follow the GitHub rules: lowercase, punctuation removed (except - and _), spaces replaced by -, duplicates suffixed with -1, -2.

Converting HTML into Markdown

parse(string $file, array $parameters = []): MarkdownConversion accepts:

  • a template of templates/ (.html.twig, .twig, .php): rendered first by the View component with $parameters
  • a .html / .htm file: converted directly
  • a .txt file: kept (line endings normalized, trimmed)

convert(string $html): string converts an HTML string. The <body> is used; script, style and head are ignored.

MarkdownConversion:

Method Description
getMarkdown(): string / __toString() the Markdown
getSource(): string the absolute path of the converted file
getDocument(): MarkdownDocument the document of the Markdown
to(string $target): string writes the file (directories created, relative to the project root) and returns its absolute path

View filter

The markdown filter converts Markdown into HTML (safe HTML, not escaped again). By default the raw HTML written in the Markdown is escaped, so the filter can be used on content written by visitors (comments, profiles):

{{ comment.body|markdown }}        {# <script> is displayed as text #}
{{ page.body|markdown(true) }}     {# trusted content: raw HTML kept #}
<?= $this->filter('markdown', $comment->getBody()) ?>
<?= $this->filter('markdown', $page->getBody(), true) ?>

A markdown filter of the application (src/Helper/View) replaces the one of the framework.

Command

php bin/neo markdown:convert templates/page/about.html.twig docs/about.md

markdown:convert <source> <target> asks both arguments when they are missing, converts the source with parse() and writes the target with to().

MarkdownManagerInterface

Method Description
get(string $file): MarkdownDocument reads a Markdown file
fromString(string $markdown): MarkdownDocument parses a string
toHtml(string $markdown): string Markdown to HTML
toSafeHtml(string $markdown): string Markdown to HTML, raw HTML escaped
parse(string $file, array $parameters = []): MarkdownConversion HTML file, template or text file to Markdown
convert(string $html): string HTML to Markdown

Errors throw NeoPHP\Package\Markdown\Exception\MarkdownException (extends FrameworkException).

Supported syntax

  • ATX (#) and setext (===, ---) headings, with an id
  • paragraphs, hard line breaks (two spaces or \)
  • emphasis and strong emphasis (*, _), strikethrough (~~text~~)
  • inline code, fenced code blocks (``` and ~~~, class="language-xxx"), indented code blocks
  • links [text](url "title"), reference links [text][ref] with [ref]: url "title", autolinks <https://...>, bare URLs (https://..., www.)
  • images ![alt](url "title")
  • blockquotes (nested, with any block inside)
  • ordered and unordered lists (nested, tight or loose, start number), task lists - [ ] / - [x]
  • tables with alignment, thematic breaks
  • raw HTML blocks and inline HTML, backslash escapes, HTML entities

The text is escaped; javascript:, vbscript: and data: URLs (except data:image) are replaced by #. toHtml(), get() and fromString() keep raw HTML as written (trusted content); use toSafeHtml() or the markdown filter without argument for untrusted Markdown.

Changelog

  • v2.0.0 — MarkdownManager is the final entry point of the module, declared with #[Package]; MarkdownManagerInterface replaces Contract\MarkdownParserInterface; Contract\AbstractMarkdownParser is merged into the manager; MarkdownConversion moves to Converter\MarkdownConversion; the internal classes are marked @internal.
  • v1.30.0 — the markdown filter escapes raw HTML by default (markdown(true) keeps it), toSafeHtml() in MarkdownParserInterface, HtmlRenderer::setEscapeHtml().
  • v1.19.0 — Markdown package: CommonMark + GFM parser, MarkdownDocument (title, description, summary, sections, links, images, code blocks), HTML and templates to Markdown, markdown view filter, markdown:convert command.