Blog

Modul des Monats Juli 2020

10.07.2020 // Renée Bäcker

Markdown ist ziemlich weit verbreitet, wenn es um Textdokumente geht. Das Format bietet auch viele Vorteile gegenüber anderen Auszeichnungssprachen:

  • Es ist schlank und es behindert den Lesefluss nicht.
  • Es ist einfach zu erlernen.
  • Für (fast) alle Sprachen gibt es Module, um es z.B. nach HTML zu konvertieren.
  • Die Integration in verschiedene Tools ist weit verbreitet.

Das Ursprungsmarkdown kann nur einen beschränkten Satz an Befehlen wie Überschriften, Hervorhebung und Links. Mit der Zeit sind – wie zu erwarten war – einige Erweiterungen entwickelt worden. So gibt es z.B. noch MultiMarkdown, CommonMark und Hoedown.

Mit diesen Erweiterungen werden dann auch Tabellen, Code-Blöcke und noch mehr unterstützt.

Wir setzen bei verschiedensten Projekte Markdown ein – z.B. sind die Artikel für dieses Blog alle in Markdown geschrieben. Das hat den Vorteil, dass wir die Texte in jedem Editor schreiben können und wenn sie auf Gitlab landen, werden sie auch im Browser gleich ansehnlich dargestellt.

Damit Sie die Artikel auch hier im Blog so ansehnlich angezeigt bekommen, müssen wir das Markdown in HTML umwandeln. Dazu setzen wir das Modul Text::Markdown::Hoedown ein.

Es ist daher unser erstes Modul des Monats!

Die Nutzung des Moduls ist ziemlich einfach:

use v5.20;
use Text::Markdown::Hoedown;

my $md = q~
# Blogartikel

Das [Perl-Academy Blog](https://blog.perl-academy.de)
enthält einige *interessante* Blogartikel
~;

say markdown $md;

Der obige Code gibt folgendes HTML aus:

$ perl hoedown/hoedown.pl 
<h1 id="toc_0">Blogartikel</h1>

<p>Das <a href="https://blog.perl-academy.de">Perl-Academy Blog</a>
enthält einige <em>interessante</em> Blogartikel</p>

Wie weiter oben schon erwähnt, enthält das Standardmarkdown nur wenige Elemente. Hoedown unterstützt aber einige Erweiterungen, die man explizit und einzeln aktivieren muss. Tabellen werden im Standard nicht unterstützt. Die Erweiterungen unterstützen aber zum Glück einheitliche Syntax, für Tabellen sieht das so aus:

my $md = q~
# veröffentlichte Artikel

Datum | Titel
------+-------
01.07.2020 | Blog-Revival
10.07.2020 | Modul des Monats Juli 2020
~;

say markdown $md

Das gibt erstmal nur

$ perl hoedown/table.pl 
<h1 id="toc_0">veröffentlichte Artikel</h1>

<p>Datum      | Titel
-----------+-------
01.07.2020 | Blog-Revival
10.07.2020 | Modul des Monats Juli 2020</p>

aus. Bei dem markdown-Aufruf kann man noch Optionen mitgeben. Unter anderem kann man hier festlegen, welche Erweiterungen aktiviert werden sollen. Für die Tabellen wäre das HOEDOWN_EXT_TABLES. Der Aufruf sieht dann folgendermaßen aus:

say markdown $md,
    extensions => HOEDOWN_EXT_TABLES;

Damit Sie die Code-Beispiele mit so einem schönen Highlighting sehen können, nutzen wir im Markdown sogenannte Fenced codes. Diese werden mit ``` eingeschlossen. Damit das korrekte Highlighting für die Programmiersprache verwendet wird, muss diese zu Beginn angegeben werden. Für Perl-Code sieht dies dann so aus:

 # Perl-Code

 ```perl
 use Text::Markdown::Hoedown;

 my $md = '# Test';
 print markdown $md;
 ```

Da das ebenfalls nicht zum Standard gehört, muss man die entsprechende Erweiterung aktivieren:

say markdown $md,
    extensions => HOEDOWN_EXT_TABLES | HOEDOWN_EXT_FENCED_CODE;

Der Code-Block ergibt folgenden HTML-Code:

<pre><code class="language-perl">use Text::Markdown::Hoedown;

my $md = &#39;# Test&#39;;
print markdown $md;
</code></pre>

Das Highlighting wird also nicht von Hoedown gemacht, sondern es wird nur ein einfacher <code>-Block erzeugt, dessen Klasse entsprechend der angegebenen Programmiersprache gesetzt wird. Für die Farbgebung hier nutzen wir prism.js.

Die Beispielprogramme habe ich in einem extra Gitlab-Repository bereitgestellt.


Permalink: