Howto: Dokumentation mit Markdown schreiben in Netbeans

Wer direkt in seiner Entwicklungsumgebung auch Dokumentationen und Readmes bearbeitet, wird sich schnell Wege überlegen, um Überschriften, Aufzählungen und Sonstiges hervorzuheben bzw. zu formatierten. Mit Markdown gibt es ein weit verbreitetes und sehr einfaches System, das sich dafür hervorragend eignet. Leider bietet Netbeans von Haus aus keine besondere Unterstützung für dieses Format.

Der Entwickler Florian Reiss hat sich dieses Problems angenommen und bietet ein entsprechendes Netbeans-Plugin auf github an.

Wer sich mit git auskennt, kann also das Projekt klonen und am besten in der eigenen Netbeans-Installation übersetzen und anschließend das erstellte Paket installieren. Alle anderen klicken auf der Github-Seite am besten auf Download ZIP, entpacken das heruntergeladene Archiv und installieren das Plugin, das sich im Unterverzeichnis nbm befindet und flow-netbeans-markdown.nbm heißt. Dazu öffnet man den Plugin-Manager (Tools / Plugins), wechselt auf den Reiter Downloaded, klickt auf Add Plugins…, wählt die oben genannte NBM-Datei aus und klickt anschließend auf Install. Nach einem Neustart ist das Plugin aktiv.

Über den Plugin-Manager kann das heruntergeladene Modul installiert werden
Über den Plugin-Manager kann das heruntergeladene Modul installiert werden

Das Plugin bietet nicht nur Syntax-Highlighting für die Markdown-Syntax, sondern kann auch direkt HTML-Dateien erzeugen und unterstützt zahlreiche Erweiterungen zur Standard-Markdown-Syntax. In den Plugin-Einstellungen (Preferences / Miscellaneous / Markdown) lassen sich die Extensions einschalten und ein Grundgerüst editieren, das bei der HTML-Generierung verwendet wird. Hier ist es etwa möglich, CSS zu notieren oder eine CSS-Datei (die allerdings dann jeweils von Hand zu kopieren ist) zu referenzieren.

In den Markdown-Einstellungen kann das HTML-Template bearbeitet werden
In den Markdown-Einstellungen kann das HTML-Template bearbeitet werden

Die Syntax von Markdown ist recht simpel und ist darauf ausgelegt, dass auch die Plain-Text-Version eines Dokumentes noch gut gelesen werden kann. Einfache Basis-Elemente sind Überschriften, Zitatblöcke und Listen:

Eine ausführliche Beschreibung von Markdown findet man hier, eine Beschreibung der Erweiterungen hier. Mit Hilfe von pandoc ist es sogar möglich, Markdown-Dateien nach ePub, PDF, LaTeX und andere Formate zu konvertieren.

Über das Kontextmenü einer MD-Datei kann eine HTML-Version generiert werden
Über das Kontextmenü einer MD-Datei kann eine HTML-Version generiert werden

Kleiner Tipp noch zum Schluss: Im Gegensatz zu Programmcode ist es natürlich empfehlenswert, bei Markdown-Dateien den Zeilenumbruch im Editor einzuschalten. Das geht von Haus aus in Netbeans nur global, was auf Dauer zu umständlich ist. Auch hier schafft ein Plugin Abhilfe: Toggle Line Wrap heißt es und kann direkt über den Plugin-Manager installiert werden. Es richtet rechts unten in der Statusleiste eine kleine Schaltfläche ein, mit der der Umbruch (nur) für die aktuelle Datei umgeschaltet werden kann.

3 Gedanken zu „Howto: Dokumentation mit Markdown schreiben in Netbeans“

Kommentare sind geschlossen.