Webkomponenten mit Stencil – Ein erster Überblick

10/09/2017

Dieser Artikel gibt eine Einführung in die Entwicklung von Webkomponenten mit Hilfe von Stencil. Stencil ist ein Kompiler für plattformunabhängige Webkomponenten, der zur Zeit vom Team hinter dem Ionic-Framework entwickelt wird und erst kürzlich im August auf dem Polymer Summit 2017 zum ersten Mal der Öffentlichkeit vorgestellt wurde.

Webkomponenten sind eine Erweiterung der HTML- und DOM-Spezifikation, die aktuell durch das Word Wide Web-Konsortium (W3C) vorgenommen wird. Es handelt sich dabei um in sich gekapselte, wiederverwendbare Widgets und Komponenten, die in Webseiten und Webapplikationen eingebunden werden können. Webkomponenten sind auch ein elementarer Bestandteil von Progressiven Web Apps (PWA), auf die wir in einem früheren Beitrag eingegangen sind.

Hier soll nun eine erste deutschsprachige Einführung in Stencil gegeben werden. Er wird erläutert, um was es sich bei Stencil handelt und wie mit dieser noch sehr neuen Technologie eigene Webkomponenten erzeugt werden können. Links zu weiterführenden Informationen rund um Stencil bzw. Webkomponenten finden sich am Ende dieses Artikels.

Kurz als Warnung: Stencil ist schon jetzt sehr rund und zumindest beim Ionic-Team auch schon im professionellen Einsatz. Aber die Software befindet sich in einem frühen Stadium und ist noch immer in der Entwicklung. Dennoch lohnt sich schon jetzt ein Blick auf diese möglicherweise zukunftsweisende Technologie.

Die folgende Kurzanleitung setzt Erfahrung mit Javascript, Git und Node.js bzw. NPM voraus. Darüber hinaus sind Grundkenntnisse in Angular, React, TypeScript und SASS hilfreich. Hier wird das Nötigste dazu kurz erklärt, kann aber in einem kurzen Artikel natürlich nicht komplett abgedeckt werden.

Inhalt

Was ist Stencil?

Stencil ist ein Kompiler, mit dessen Hilfe plattformunabhängige Webkomponenten erstellt werden können. Konkret werden mit Hilfe von Stencil benutzerdefinierte Elemente (Custom Elements) erzeugt, wobei der erzeugte Code aus nichts weiter als Vanilla-JavaScript, HTML und CSS besteht und daher in jedem modernen Browser ausführbar ist.

Webkomponenten gemäß der V1-Spefizikation werden von Haus aus in den Browsern Chrome und Safari dargestellt, während für Edge und Firefox an der Unterstützung gearbeitet wird. Stencil verwendet jedoch einen dynamischen Lader, über den mit Hilfe sogenannter Polyfills schon heute weitaus mehr Browser die von Stencil erzeugte Webkomponenten unterstützen: zusätzlich zu Chrome und Safari auch Firefox, Edge und sogar der Internet Explorer 11. Der aktuelle Stand findet sich auch auf caniuse.com.

Stencil ist also weder ein neues Framework, noch eine Bibliothek. Vielmehr können die mit Stencil erzeugten Webkomponenten in beliebigen anderen Frameworks genutzt oder auch einfach direkt in den HTML-DOM eingebunden werden. Das macht sie zu flexiblen, wiederverwendbaren Bausteinen moderner Webseiten und Webanwendungen wie PWAs.

Bevor wir uns gleich eine Beispiel-Webkomponente mit Hilfe von Stencil erzeugen, eine kurze Übersicht zu den Eigenschaften von Stencil-Webkomponenten und ihre Vorteile:

Eigenschaften von mit Stencil erzeugten Webkomponenten

Stencil vereint in sich einige bewährte sowie einige sehr neue Konzepte anderer Frameworks wie Angular oder React:

  • Virtueller DOM – eine Repräsentation des eigentlichen DOMs, über die eine schnellere Bearbeitung und Aktualisierung desselben erfolgen kann; ähnlich wie es die Frameworks Vue.js und React umsetzen.
  • Lazy Loading – die Komponenten werden asynchron und damit deutlich schneller geladen und können mit anderen weiteren Komponenten kombiniert werden.
  • Asynchrones Rendering – ähnlich wie in der Entwicklerversion von React („Fiber“) gelöst.
  • Reaktives Data-Binding – reaktive Bindung zwischen den Daten im DOM und in der Komponente.
  • TypeScript – wie schon Angular oder Ionic unterstützt auch Stencil im Quellcode TypeScript, die Erweiterung des neuen ECMAScript-Sprachkerns u.a um Klassen, Interfaces und statische Typisierung.
  • JSX – eine einbettbare XML-artige Syntax, aus der JavaScript-Code erzeugt wird; als Teil von React entwickelt wird JSX nun auch von TypeScript unterstützt.

Vorteile von mit Stencil erzeugten Webkomponenten

Mit Stencil erzeugte Webkomponenten weisen einige Vorteile gegenüber herkömmlichen Ansätzen auf:

  • Performance – die Komponenten sind im Vergleich zu Lösungen mittels Frameworks ohne unnötigen Ballast und dementsprechend schnell.
  • Stabilität – der Code besteht aus bewährtem Standard-Javascript/HTML/CSS und unterliegt daher nicht den permanenten Versionsänderungen moderner Frameworks.
  • Interoperabilität – die Komponenten lassen sich in allen größeren Frameworks verwenden.
  • Vertrautheit – viele bewährte Elemente anderer Frameworks sind in kompakter Form auch in Stencil realisiert worden.

Die Beispiel-Webkomponente

Das Stencil-Team stellt auf GitHub eine einfache Beispiel-Webkomponente zur Verfügung, die mittels Git einfach heruntergeladen werden kann. Über NPM werden dann alle erforderlichen Module nachgeladen und installiert:

$ git clone https://github.com/ionic-team/stencil-starter.git my-app
$ cd my-app
$ git remote rm origin
$ npm install

Der Quellcode der Webkomponente befindet sich im Unterordner src. Dieser wird mit dem Befehl npm start kompiliert und die erzeugte Webkomponente im Unterordner www abgelegt:

$ npm start

> @stencil/starter@0.0.1 start /home/onno/Development/Stencil/my-app
> npm run dev
> @stencil/starter@0.0.1 dev /home/onno/Development/Stencil/my-app
> sd concurrent "stencil build --dev --watch" "stencil-dev-server"

[34:13.0]  build, dev mode, started ...
[34:13.0]  compile started ...
[34:15.2]  compile finished in 2.18 s
[34:15.2]  bundle styles started ...
[34:15.2]  bundle modules started ...
[34:15.3]  bundle styles finished in 146 ms
[34:15.4]  bundle modules finished in 220 ms
[34:15.4]  build finished, watching for changes... in 2.45 s

Unsere erste Stencil-Webkomponente ist damit schon fertig. Schauen wir sie uns an!

Um die Komponente mit einem Browser anzuschauen, muss der Inhalt des www-Ordners samt der index.html-Datei durch einen Server ausgeliefert werden. Dazu kann der Inhalt des www-Ordners einfach auf einen Server übertragen werden. Noch einfacher ist es mit dem kleinen Webserver, den Stencil gleich mitliefert und der automatisch nach dem obigen Kompilierungsprozess gestartet wird. Dieser liefert über die URL http://localhost:3333/ die Webkomponente an einen Browser aus und erneuert die Ausgabe auch automatisch nach jeder Änderung am Code.

Die Ausgabe der Beispiel-Webkomponente in zunächst wenig spektakulär:

Die Ausgabe der Beispiel-Webkomponente.

Dahinter verbirgt sich aber ein höchst flexibler Mechanismus, mit dessen Hilfe auch deutlich komplexere Darstellungen komfortabel umgesetzt werden können. Im Folgenden werfen wir einen Blick auf den sich hinter der Ausgabe verbergenden Quellcode.

Ein Blick in den Quellcode

Schauen wir als erstes auf die Datei index.html im src-Ordner. Diese enthält eine ganz normale einfache HTML-Webseite:

<!DOCTYPE html>
<html dir="ltr" lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0,
        minimum-scale=1.0, maximum-scale=1.0, user-scalable=no">
  <title>Stencil Starter App</title>
  <script src="build/app.js"></script>
</head>
<body>

  <my-name first="Stencil" last="JS"></my-name>

</body>
</html>

Oben im Header wird die Webkomponente app.js geladen, welche durch den Stencil-Kompiler erzeugt wurde. Diese befindet sich natürlich nicht im src-Ordner, sondern wurde von Stencil unter www/build/ abgelegt. Beim Erzeugen der Webkomponente wurde auch die index.html-Datei aus dem src-Ordner in den www-Ordner kopiert.

Die Webkomponente wird in der index.html ganz einfach durch das dazu gehörige Custom Element my-name eingebunden:

  <my-name first="Stencil" last="JS"></my-name>

Hier werden auch gleich zwei Input-Parameter für die Webkomponente gesetzt: first und last, welche durch die Komponente ausgewertet werden. Die dazu gehörige Programmlogik der Webkomponente steckt in der Datei my-name.tsx, welche sich im Ordner src/my-name/ befindet. Die Datei trägt die Endung .tsx, da sie TypeScript- und JSX-Code enthält:

import { Component, Prop } from '@stencil/core';

@Component({
  tag: 'my-name',
  styleUrl: 'my-name.scss'
})
export class MyName {

  @Prop() first: string;
  @Prop() last: string;

  render() {
    return (
      <p>
        Hello, my name is {this.first} {this.last}
      </p>
    );
  }
}

In der ersten Zeile werden jene Teile aus dem Paket @stencil/code importiert, die wir für die Datei benötigen. Das ist zunächst der @Component()-Dekorator. Dekoratoren (engl. decorators) wurden mit TypeScript bzw. ECMAScript6 eingeführt. Mit ihrer Hilfe kann einer Klasse zusätzliche Meta-Angaben hinzugefügt werden. Hier ist dies der Name des HTML-Elements der Komponente (tag) sowie die für die Optik der Komponente zuständige SASS-Datei (styleURL). Aus der SASS-Datei erzeugt der Kompiler dann die CSS-Datei.

Es folgt die Definition der Klasse MyName, welche mit dem Setzen zweier @Prop()-Dekoratoren beginnt. Mit diesen werden der Klasse zwei Argumente first und last zur verfügung gestellt, die öffentlich (public) sind und deren Werte im Custom Element gesetzt werden. Da dies in TypeScript geschieht, wird den Argumenten auch der Typ (hier: string) mitgegeben.

Schließlich wird in der render()-Funktion die Ausgabe der Webkomponente definiert. In diesem Fall ist dies ein Absatz mit einem einzigen Satz, bei dem die beiden Argumente first und last eingesetzt werden. Die Funktion render() enthält eine deklarative Template-Syntax wie sie mit JSX eingeführt wurde. Die mit @Props() definierten Eigenschaften werden von der Komponente überwacht und bei jeder Änderung der Werte wird die render()-Funktion erneut aufgerufen.

Die Ausgabe kann auch Entscheidungen, Schleifen und weitere Eingaben enthalten. Einen Überblick gibt die Stencil-Webseite. Auf der Webseite werden auch die weiteren Elemente der Stencil-API erläutert:

  • @Component() – wie oben erwähnt, werden damit der tag des Custom Elements sowie das zu verwendende style sheet festgelegt.
  • @Prop() – erzeugt eine Eigenschaft der Komponente, die vom Custom Element aus gesetzt wird ist. Änderungen bewirken ein erneutes Rendern der Komponente.
  • @State() – erzeugt einen internen Zustand der Komponente, der nicht von außen zugänglich ist. Änderungen bewirken ein erneutes Rendern der Komponente.
  • @Method() – wird verwendet, um eine Methode der Komponente zu veröffentlichen, d.h. dem Custom Element zugänglich zu machen.
  • @Event() – erzeugt benutzerdefinierte DOM-Events, um Daten und Events an andere Komponenten zu senden.
  • @Listen() – Hört (listen) auf Events, die von Kinderkomponenten ausgedendet werden.
  • @Element() – gibt eine Instant eines HTML-Elementes zurück, um es der Komponente zugänglich zu machen.

Darüber hinaus verwendet Stencil weitere Konzepte wie Hooks, die zu definierten Punkten im Lebenszyklus einer Komponente aufgerufen werden, serverseitiges Rendering oder auch einen eigenen Router, über den Webkomponente über festgelegte URL-Pfade gestartet werden können.

Anwendungsbeispiele für Stencil-Webkomponenten

  • Eine StencilNews-PWA bestehend aus Stencil-Webkomponenten.
  • Die Stencil-Webseite besteht ebenfalls komplett aus Stencil-Webkomponenten und ist im Quellcode auch auf GitHub veröffentlicht.
  • Eine persönliche Webseite als PWA mit Stencil-Webkomponenten von Fer. D. Olmo.

Weitere Informationen

Zum Thema Webkomponenten:

Zu Stencil:




Progressive Web Apps – eine kurze Übersicht

24/08/2017

Progressive Web Apps sind der neue heilige Gral in der Welt der Webanwendungen. Seit Google den Begriff 2015 geprägt hat, gewinnt das Konzept der PWAs mehr und mehr an Popularität. Es könnte dabei die Art und Weise, wie wir Webanwendungen entwickeln und verwenden, in den kommenden Jahren vollständig umkrempeln.

Die Idee hinter PWAs: Statt eine Anwendung (beispielsweise einen Onlineshop) auf einer Webseite und parallel als Apps für verschiedene Plattformen wie iOS oder Android anzubieten – samt dem damit verbundenen mehrfachen Entwicklungsaufwand – wird die Anwendung in eine einzige, plattformunabhängige Progressive Web App gesteckt.

Aus Anwendersicht ist eine PWA nichts weiter als eine App mit einem responsiven Layout, die auch offline funktioniert und die per Browser über eine URL erreichbar ist, aber gleichzeitig auch dauerhaft auf dem Homescreen von mobilen Geräten gespeichert werden kann.
Aus Entwicklersicht ist eine PWA ein Bündel aus HTML5, CSS3 und JavaScript, bei dem ein sogenannter Service Worker die Offline-Funktionalität bereitstellt und die über HTTPS mit einem Server kommuniziert.

Im Folgenden sollen kurz die Eigenschaften von PWAs und ihre möglichen Folgen für die App-Entwicklung skizziert werden. Am Ende werden verschiedene Tools und Frameworks für die Entwicklung von PWAs vorgestellt.

Eigenschaften von PWAs

Schauen wir wie Google Progressive Web Apps definiert, finden wir unter anderem eine Checkliste für PWAs, wie Google’s Lighthouse-Tool sie vorgibt, mit dem u.a. die Performance und Qualität von PWAs getestet werden kann. Zusammengefasst hat eine PWA folgende Eigenschaften:

Progressivität
Eine PWA läuft auf jedem Gerät und in jedem Browser (so jedenfalls die Idee; bisher noch nicht überall erreicht, siehe weiter unten).
Responsive
Das Layout der PWA passt sich an die Bildschirmauflösung von Desktop-Monitoren, Tablets und Smartphones an.
Offline-Funktionalität
Die PWA funktioniert grundsätzlich auch offline oder mit einer schlechten Internetverbindung.
Sicherheit
Die PWA wird über verschlüsseltes HTTPS ausgeliefert und kommuniziert auch ausschließlich über HTTPS.
Push-Nachrichten
Benutzerinnen und Benutzer können per Push-Nachrichten auf die PWA aufmerksam gemacht werden.
Installierbarkeit
PWAs lassen sich direkt aus dem Browser heraus auf dem Homescreen installieren. Sie benötigen daher keinen App-Store mehr.
Verlinkbarkeit
einfache Verbreitung über eine URL. Keine komplizierte Installation mehr.

Was haben PWAs für Folgen?

Wenn mehr und mehr Funktionalität in die Browser übertragen wird, inklusive Hardware-Unterstützung wie das Auslesen der Kamera und anderer Sensoren wie zum Beispiel des Standardortes über GPS und dergleichen, sind Progressive Web Apps auf dem besten Weg, einige herkömmliche Technologien überflüssig zu machen. Bis heute sind noch SDKs für native Apps oder beispielsweise Apache Cordova/Phonegap für hybride Apps notwendig, um einer App diese Hardware-Unterstützung zu bieten. Sobald dies über den Browser angeboten wird, können PWAs die meisten Aufgaben herkömmlicher Apps übernehmen.

Den Gedanken zu Ende gedacht könnte die Zukunft von Betriebssystemen für mobile Geräte allein aus einer Kombination aus Kernel und Browser bestehen.

Bisher wurden Apps primär über die App-Stores für Android und iOS ausgeliefert. Eine PWA, die direkt über den Browser heraus dauerhaft installiert werden kann, macht solche Stores überflüssig. Dazu kommt der große Vorteil, dass PWAs direkter und damit schneller aktualisiert werden können. Das geht bis zu der Idee, dass für kleine Änderungen auch nur die entsprechenden Komponenten aktualisiert werden statt die ganze App auf einmal.

PWAs ermöglichen einen direkteren Kontakt zwischen Entwicklerinnen und Entwicklern mit den Usern ihrer Apps.

Beispiele für PWAs

Umfangreiche Listen der verschiedensten PWAs bieten u.a. Google’s PWA-Verzeichnis sowie die Liste von PWAs in der englischen Wikipedia.

Eine PWA entwickeln

Progressive Web Apps basieren auf zwei durch das des WWW-Konsortium W3C festgelegte Spezifikationen: dem Web App Manifest und den Service Workers. Praktisch wird eine PWA in HTML5, CSS3 und JavaScript umgesetzt, wobei der Service Worker die Offline-Funktionalität bereitstellt.

Der Service Worker ist eine in JavaScript geschriebene Browsertechnologie, die im Hintergrund läuft und vor allem zwei Funktionen vorhält: Die Speicherung von Daten und Inhalten unabhängig von einer Internetverbindung sowie die Annahme von Push-Nachrichten, die von einem Server gesendet werden.

Der Service Worker ist auch der Grund dafür, dass PWAs noch nicht auf allen Browsern lauffähig sind. Dies betrifft vor allem die Browser Safari und Edge, für die aber bereits an einer Implementierung des Service Workers gearbeitet wird. Der aktuelle Stand des Supports für verschiedene Browser kann auf der Webseite Is Service Worker Ready Yet? abgerufen werden.

Zusätzlich kann die Entwicklung durch die Verwendung von Frameworks erleichtert werden, die viele der benötigten Funktionen und Elemente schon von Haus aus mitbringen:

Angular
ist ein TypeScript- bzw. JavaScript-basiertes Webapplikationsframework für das Front-End. Um Verwechselungen zu vermeiden wird der Vorgänger statt Angular 1 mittlerweile AngularJS genannt, während die aktuelle Version schlicht Angular heißt. Angular wird von Einzelpersonen und Unternehmen unter der Führung Googles entwickelt und steht unter der freien MIT-Lizenz. Mehr dazu auf der Angular-Webseite.
Polymer
ist eine freie, unter der BSD-Lizenz stehende JavaScript-Bibliothek für die Entwicklung von Webanwendungen mittels Web-Komponenten. Polymer wurde im Mai 2015 von Google veröffentlicht und mittlerweile in verschiedenen Google-Diensten eingesetzt. Mehr dazu auf der Polymer-Webseite.
Vaadin
ist ein freies, unter der Apache-Lizenz stehendes Framework mit Fokus auf der Entwicklung von Web-Komponenten, wobei die Logik vor allem in Java auf der Serverseite untergebracht ist. Mittels Polymer können Vaadin-Komponenten in PWAs integriert werden. Mehr auf der Vaadin-Webseite.

Ganz frisch veröffentlicht ist Stencil, ein Kompiler mit dem plattformunabhängige Web-Komponenten für PWAs erstellt werden können. Mehr dazu auf der Stencil-Webseite. Stencil wurde im August 2017 auf dem Polymer Summit vom Ionic-Team vorgestellt, die mit zu den PWA-Vorreitern gehören.

Zusammengefasst

PWAs haben das Potenzial, die Art und Weise wie wir Apps entwickeln und benutzen zu revolutionieren. Sollten PWAs sich in der breiten Masse durchsetzen, wird dies zudem einen starken Einfluss auf das Betriebssystem auf mobilen Geräten haben und nicht zuletzt völlig neue Vertriebswege von Apps abseits der althergebrachten Stores auftun.




Dokumentationen und Anleitungen mit Markdown + Pandoc

25/07/2017

Einleitung

Texte für verschiedene Ausgabeformate erstellen wir bei Data·Code·Design im Markdown-Format und konvertierten diese mit Pandoc in das jeweils benötigte Ausgangsformat. Der große Vorteil ist dabei, dass ein Text nur einmal in Markdown geschrieben werden muss und mit dem flexiblen Konverter Pandoc direkt in verschiedene Formate wie beispielsweise HTML, PDF, DOCX oder EPUB umgewandelt werden kann.

Die Kombination aus Markdown + Pandoc übernimmt bei der Konvertierung die Schwerstarbeit, indem sie aus einem einfachen Quelltext automatisch die Formatierungen für Überschriften, Fußnoten, interne und externe Links, das Inhaltsverzeichnis und vieles mehr erzeugt. Selbst die sonst eher komplizierte Generierung von E-Books im EPUB– oder Amazon’s Mobipocket-Format ist dank Pandoc einfach zu realisieren.

Hier sollen kurz Markdown und Pandoc vorgestellt werden. Am Ende des Beitrags werden zudem zwei plattformunabhängige Editoren zur Erstellung von Markdown-Texten vorgestellt.

Markdown – die vereinfachte Auszeichnungssprache

Markdown ist eine vereinfachte Auszeichnungssprache, bei der die Textformatierung über verschiedene Satzzeichen gesteuert wird. Dabei ist die Quelldatei auch ohne die Konvertierung in ein Ausgabeformat schon leicht lesbar und entsprechend leicht zu bearbeiten. Mittels verschiedener Konvertierungstools kann eine solche Quelldatei in eine Vielzahl von Ausgangsformaten umgewandelt werden.

Es folgende einige Beispiele für Text-Formatierungen. Kapitelüberschriften werden beispielsweise durch eine oder mehrere voran gestellte Rauten erzeugt:

# Kapitel (Ebene 1)
## Unterkapitel (Ebene 2)

Im Ausgabeformat HTML wird daraus dann:

<h1>Kapitel (Ebene 1)</h1>
<h1>Unterkapitel (Ebene 2)</h2>

Fetter Text, kursiver Text oder durchgestrichener Text wird einfach durch folgende Satzzeichen erzeugt:

**Fetter Text**, *kursiver Text* oder ~~durchgestrichener Text~~

Geordnete und ungeordnete Listen werden ebenfalls durch voran gestellte Satzeichen erzeugt. Aus folgendem Markdown:

* ungeordneter Listeneintrag 1,
- auch mit Minus-Zeichen möglich,
+ oder auch durch ein Plus-Zeichen.

1. Erster geordneter Listeneintrag
1. Zweiter Listeneintrag -- die Zahl ist egal, die Nummerierung wird einfach automatisch vorgenommen.
2. Dritter Listeneintrag

werden die folgenden Listen generiert:

  • ungeordneter Listeneintrag 1,
  • auch mit Minus-Zeichen möglich,
  • oder auch durch ein Plus-Zeichen.
  1. Erster geordneter Listeneintrag
  2. Zweiter Listeneintrag – die Zahl ist egal, die Nummerierung wird einfach automatisch vorgenommen.
  3. Dritter Listeneintrag

Die Markdown-Syntax ist also sehr einfach gehalten und damit auch entsprechend schnell zu lernen. Weitere Formatierungen umfassen Tabellen, Zitate, Programmcode, Links und einiges mehr. Mehr dazu findet sich auf der Webseite des Markdown-Entwicklers (Englisch), die auch auf Deutsch übersetzt wurde. Eine Erweiterung der Markdown-Syntax bietet das Pandoc-Paket an, das im Folgenden beschrieben wird.

Pandoc – der flexible Parser für Multidokumentenformate

Pandoc ist ein Parser für Multidokumentenformate, der seit 2007 von John MacFarlane unter der freien GPL-Lizenz angeboten und weiterentwickelt wird. Pandoc kann Dokumente in verschiedenen Format lesen und in eine Vielzahl von Ausgabeformaten konvertieren. Die Formate umfassen u.a. Markdown, HTML, LaTeX, Microsoft Word oder LibreOffice oder EPUB (siehe auch die Übersicht auf der Pandoc-Webseite). Pandoc kann unter Windows, Linux/BSD oder Mac OS X installiert werden und wird über die Kommandozeile aufgerufen.

Wer es ohne Installation von Pandoc einmal ausprobieren möchte: Auf der Pandoc-Webseite wird eine Demo mit einem Online-Konverter angeboten, mit dem Texte von einem in ein anderes Format umgewandelt werden können.

Nach der Installation bietet Pandoc einen interaktiven Modus, an mit dem die Konvertierung von einem Format in ein anderes demonstriert werden kann. Mit den Optionen -f und -t wird das Ein- bzw. Ausgabeformat festgelegt. Um zum Beispiel einen Markdown-Text nach HTML umzuwandeln reicht folgender Befehl:

pandoc -f markdown -t html

Wird dann die Zeile

<p>Hello <em>pandoc</em>!</p>

eingegeben, wird mit Ctrl+D daraus in HTML:

<p>Hallo <em>Welt</em>!</p>

Um nun eine ganze in Markdown vorliegende Datei in ein HTML-Dokument umzuwandeln reicht folgender Befehl:

pandoc dateiname.md -f markdown -t html -s -o dateiname.html

Mit der Option -o wird der Name der Ausgabedatei angeben. Die Option -s steht für standalone und sorgt dafür, dass die Datei vollständig samt Header und Footer erstellt wird, und nicht nur der Inhalt als Fragment.

Die Dateiformate kann Pandoc übrigens auch an der Dateiendung erkennen. Obiger Befehl kann also auch kurz wie folgt geschrieben werden:

pandoc dateiname.md -s -o dateiname.html

Eine weitere oft genutzte Option ist --smart, die unter anderem dafür sorgt, dass Bindestriche korrekt übersetzt werden. Aus -- und --- werden so verschieden lange Gedankenstriche („–“ bzw. „—“, statt dem einfachen Bindestrich „-“).

Mit --toc wird automatisch ein Inhaltsverzeichnis aus dem im Dokument vorkommenden Überschriften erzeugt. Mit --toc-depth=N werden dabei Überschriften bis zu einer Tiefe N berücksichtigt.

Eine ausführliche Dokumentation zu Pandoc findet sich auf der Pandoc-Webseite (Englisch) oder auch in einem Artikel auf Deutsch auf Pro-Linux.

Passende Texteditoren

Die Markdown-Textdateien können prinzipiell mit jedem beliebigen Texteditor geschrieben werden, allerdings bieten einige Editoren deutlich mehr Komfort beim Schreiben von Markdown-Texten. Hier sollen zwei Editoren vorgestellt werden, Atom und Visual Studio Code, die beide mittels Erweiterungen sehr praktische Zusatzfunktionen für Markdown anbieten, die weit über einfaches Syntax Highlighting hinaus gehen. Sowohl Atom als auch Visual Studio Code basieren auf dem modernen Electron-Framework und sind sowohl für Windows, Linux als auch macOS verfügbar. Beide sind kostenlos unter der quelloffenen MIT-Lizenz veröffentlich worden.

Atom

Atom-EditorAtom wird vom Projekt-Hosting-Dienst GitHub entwickelt und in einer stabilen Version seit Februar 2016 angeboten. Atom unterstützt fast alle Programmiersprachen und ist über sogenannte Packages sehr flexibel erweiterbar. Mit dem Package markdown-preview-plus ist beispielsweise eine Vorschaufunktion für Markdown verfügbar, die sogar spezielle Pandoc-Befehle mit berücksichtigt. Atom kann auf der offiziellen Webseite herunter geladen werden.

Visual Studio Code

VSCode-EditorVisual Studio Code (oder kurz VS Code) ist der etwas neuere Stern am Editor-Himmel, der von Microsoft entwickelt und seit April 2016 angeboten wird. Der Fokus liegt auf der Entwicklung von Webanwendungen und der Software-Entwicklung in diversen Programmiersprachen. Mit Markdown all in one steht aber auch eine Erweiterung des Editors zur Verfügung, die das Schreiben von Texten in Markdown extrem erleichtert. So bietet die Erweiterung unter Anderem diverse Textformatierungen mittels Tastenkombinationen an, eine automatisch aktualisierte Vorschau sowie ein Generator für Inhaltsverzeichnisse. VS Code kann auf der offiziellen Webseite herunter geladen werden.

Versionsverwaltung mittels Git

Sowohl Atom als auch Visual Studio Code haben schon in der Grundversion Git implementiert. Git ist eine sehr flexible, dezentrale Versionsverwaltung, mit deren Hilfe sich die Historie von Quelltexten festhalten lässt.

Die Entwicklung eines Textes kann sogar in verschiedenen Zweigen verfolgt werden, wenn zum Beispiel mehrere Personen parallel an einem Text oder einem Programmcode arbeiten. Die Zweige lassen sich jederzeit auch wieder zusammenführen. Eine der große Stärken von Git ist dabei, das die verschiedenen Versionen automatisch zusmmengeführt werden. Natürlich lassen sich auch frühere Versionen eines Textes schnell und einfach wieder herstellen.

Eine ausführliche Beschreibung zur Benutzung von Git findet sich auf der Git-Webseite (Englisch) oder in der deutschen Übersetzung des Buches “Pro Git”, sowie natürlich in den Dokumentation zu den Texteditoren Atom und VS Code.