nette-markdown

nette-markdown je rozšíření pro Nette, které převádí Markdown na HTML přes league/commonmark a do Latte přidává filtr |markdown, jenž ze vstupu odstraní HTML a zablokuje odkazy javascript:.

nette-markdown: ukázkový Markdown s tabulkou, seznamem úkolů, značkou script a odkazem javascript: a jeho bezpečný převod filtrem |markdown

nette-markdown je rozšíření pro Nette, které převádí Markdown na HTML přes knihovnu league/commonmark a v šablonách Latte k tomu přidává filtr |markdown. Hodí se všude, kde text píšou lidé mimo redakci: komentáře, popisy produktů od prodejců, odpovědi v helpdesku, interní wiki. Uživatel chce tabulku, odrážky a odkaz, ale jakmile mu formulář dovolí HTML, vloží někdo dřív nebo později <script> nebo odkaz s javascript:. Markdown dá formátování, které lidé znají z GitHubu a chatů, a nette-markdown se stará, aby se z něj na stránku nedostalo nic spustitelného.

Co filtr udělá s cizím textem

Snímek nahoře ukazuje skutečný převod. Vstup obsahoval nadpis, tabulku se zarovnáním sloupců, seznam úkolů, přeškrtnutý text, holou adresu, značku <script>, odkaz [Klikni](javascript:alert(1)) a zvýraznění ==zvýrazni==. Na výstupu je tabulka s align="left" a align="right", zaškrtávací políčka jako vypnuté <input>, přeškrtnutí jako <del>, adresa převedená na odkaz a zvýraznění jako <mark>. Značka <script> zmizela celá i s obsahem a z odkazu zbyl jen text v <a> bez atributu href. Šablona přitom obsahovala jediný řádek, {$text|markdown}; převodník měl v konfiguraci rozšíření commonmark, gfm a mark.

Dva filtry pro dvě míry důvěry

Rozšíření registruje do každého Latte\Engine v kontejneru tři filtry. |markdown a |markdownSafe vždy volají bezpečný převod: HTML ze vstupu se odstraní a odkazy se schématy jako javascript:, vbscript: nebo data: se zablokují, ať je v konfiguraci cokoli. Bezpečný převod používá rozšíření z konfigurace (poznámky pod čarou, obsah, zvýraznění), a proto se na snímku ==zvýrazni== změnilo na <mark>; vynucuje jen html_input: strip a allow_unsafe_links: false. |markdownRaw převádí přesně podle konfigurace včetně html_input: allow a patří jen na text z vlastní redakce. Filtry vracejí objekt Latte\Runtime\Html, takže je Latte podruhé neescapuje a |noescape se nepíše.

V presenteru nebo službě je k dispozici MarkdownConverter se stejnými dvěma metodami, convert() a convertSafe(). Jde vytvořit i bez Nette, prostým new MarkdownConverter().

Rozšíření podle toho, co text potřebuje

Výchozí sada je CommonMark a GFM, tedy tabulky, seznamy úkolů, přeškrtnutí a automatické odkazy. Dalších šest se zapíná v konfiguraci jménem:

  • footnote pro poznámky pod čarou ve tvaru [^1],
  • smartpunct pro typografické uvozovky, pomlčky a trojtečku,
  • heading_permalink pro kotvy u nadpisů s nastavitelným symbolem,
  • toc pro obsah složený z nadpisů,
  • mark pro ==text== převedený na <mark>, vlastní rozšíření balíčku,
  • external_link pro odkazy ven s rel="nofollow noopener noreferrer", výjimkou pro vlastní domény a volitelným otevíráním v novém okně.

Překlep v názvu rozšíření neprojde potichu: konstruktor vyhodí InvalidArgumentException se seznamem známých jmen. Režim HTML ze vstupu má tři hodnoty, strip (výchozí), escape a allow, a schéma konfigurace jinou nepřijme.

Proč ne vlastní napojení na commonmark

league/commonmark sám o sobě umí všechno výše uvedené, ale v Nette aplikaci je potřeba prostředí sestavit, rozšíření zaregistrovat, filtr přidat do Latte a hlídat, aby každá šablona s cizím textem použila bezpečnou variantu. Tenhle balíček to dělá jedním řádkem v config.neon a bezpečnou variantu dává pod nejkratší jméno, takže kratší zápis je zároveň ten bezpečnější.

Testy a vydání

Repozitář má 22 testů v PHPUnit 10 se 43 kontrolami: tabulky, seznamy úkolů, přeškrtnutí, automatické odkazy, bloky kódu, odstranění HTML, blokování nebezpečných odkazů, poznámky pod čarou, kotvy nadpisů, neznámé rozšíření, atributy odkazů ven, zvýraznění mark, bezpečný převod s rozšířeními z konfigurace a filtry Latte. Na PHP 8.2 i 8.4 všechny prošly. GitHub Actions je pouštějí na PHP 8.2, 8.3 a 8.4 a po úspěšném běhu aktualizují balíček na Packagistu.

Jak začít

composer require nks-hub/nette-markdown
extensions:
    markdown: NksHub\Markdown\DI\MarkdownExtension

markdown:
    extensions: [commonmark, gfm, footnote, mark]
    html_input: strip

Potřeba je PHP 8.2 nebo novější, league/commonmark 2.8+, nette/di 3.1 a Latte 3. Verze 1.2.0 z 22. března 2026 přepnula výchozí filtr na bezpečný převod a přidala atributy pro odkazy ven; poslední je 1.2.1 ze 6. listopadu 2026.

Zdrojový kód

Kód je na GitHubu v repozitáři nks-hub/nette-markdown pod licencí MIT, balíček na Packagistu jako nks-hub/nette-markdown. Editor s tlačítky pro Markdown i Texy je samostatný projekt texy-ts-editor.

← Všechny reference