Markdown lernen: Das Schreibwerkzeug für Softwareentwickler

Wenn Sie ein Softwareentwickler sind, haben Sie wahrscheinlich viel Zeit damit verbracht, Ihre Umgebung zu verfeinern, um Ihre Produktivität zu steigern. Sie haben Ihre Lieblings-IDE. Sie haben Ihren bevorzugten Debugger. Sie haben Ihr bevorzugtes Tool zur Leistungsüberwachung. Aber was ist mit Ihrem Werkzeug zum Schreiben von Dokumentationen, Handbüchern und Berichten? Schließlich nimmt das Schreiben einen nicht unerheblichen Teil Ihrer Zeit in Anspruch, nicht wahr? In der Tat ist es an der Zeit, sich ernsthaft mit Ihrem Schreibwerkzeug zu befassen.

Und denken wir daran, dass Sie technisch versiert sind , also können WYSIWYG-Editoren die beste Option für Sie sein oder auch nicht. Sie möchten (oder möchten sogar!) nicht unbedingt durch Menüs, Symbolleisten und Menübänder navigieren, um Ihren Text zu formatieren.

Was wäre also, wenn Sie stattdessen alle Ihre Formatierungsstile als einfache Inline-Syntax direkt in den Text einfügen könnten, um einen vollständig formatierten Text zu erhalten?

Nun, in der Tat können Sie. Das ist Markdown und darum geht es in diesem Tutorial.

Wenn mehr weniger ist …

Textverarbeitungssoftware wurde geschrieben, um ein extrem breites Spektrum von Benutzern und Anwendungsfällen zufriedenzustellen, und muss daher alle Arten von Funktionen bieten. Aber natürlich ist wahrscheinlich nur ein kleiner Teil dieser Funktionalität für jeden einzelnen Benutzer relevant. Und für die meisten Benutzer, die einfach nur ein Dokument erstellen möchten (und keine Marketingbroschüre oder Poster entwerfen müssen), ist eine sehr kleine Teilmenge der vielen, vielen verfügbaren Optionen relevant.

Tatsächlich hat Microsoft dies vor einigen Jahren klar erkannt, als sie die Benutzeroberfläche von Microsoft Word in verschiedene funktionale Gruppierungen umgestalteten, die sie „Ribbons“ nannten. Interessanterweise werden Ihnen die meisten Benutzer sagen, dass sie die neue Benutzeroberfläche verwirrender und schwieriger zu navigieren fanden als ihren Vorgänger.

Tatsächlich kann mehr manchmal weniger sein, wenn es um Benutzerfreundlichkeit und Produktivität geht.

… und wenn weniger mehr ist

Seien Sie ehrlich, Sie sind Softwareentwickler, kein Grafikdesigner. Sie wollen einfach nur dieses Handbuch, dieses technische Dokument oder diesen Bericht schreiben und damit fertig sein. Sie werden mit einigen grundlegenden Formatierungsfunktionen wie Überschriften, Aufzählungen oder nummerierten Listen und Codeblöcken sehr glücklich und zufrieden sein. Und, oh ja, eine Schriftartformatierung (fett, kursiv usw.) wäre auch hilfreich. Das ist alles. (Und Mann, wenn Sie es auch nur in vi machen könnten, wäre das wirklich großartig!)

Geben Sie Markdown ein.

Was ist Markdown?

John Gruber (mit erheblichen Beiträgen des technischen Gurus und Internetaktivisten Aaron Swartz) hat die Markdown-Sprache im Jahr 2004 mit dem Ziel entwickelt, Menschen zu ermöglichen, „in einem einfach zu lesenden, einfach zu schreibenden Klartextformat zu schreiben, und optional Konvertieren Sie es in strukturell gültiges XHTML (oder HTML)“.

Markdown wurde so konzipiert, dass es so wie es ist lesbar ist, ohne dass es so aussieht, als wäre es mit Tags oder Formatierungsanweisungen markiert worden (im Gegensatz zu Text, der mit einer Auszeichnungssprache wie RTF oder HTML formatiert ist, die in seinem Rohformat sowohl schwer zu erstellen als auch schwer zu lesen sein kann ).

Mit Markdown können Sie in einem einfach zu lesenden, einfach zu schreibenden Nur-Text-Format schreiben, das dann in strukturell gültiges HTML konvertiert werden kann. Um ganz genau zu sein, ist Markdown also eigentlich zwei Dinge:

1. Eine Nur-Text-Formatierungssyntax
2. Ein Softwaretool (dessen erste Version in Perl geschrieben wurde), das die einfache Textformatierung in HTML umwandelt.

Markdown enthält eine Handvoll einfacher, ziemlich intuitiver und benutzerfreundlicher Syntaxkonventionen. Besonders für Sie als Softwareentwickler – der sich nicht davon abschrecken lässt, diese grundlegenden Syntaxkonventionen lernen und anwenden zu müssen – kann Markdown in der Tat der Weg des geringsten Widerstands zwischen dem, was Sie schreiben möchten, und dem Geschriebenwerden sein.

Markdown lernen: Erste Schritte

Markdown ist leicht zu erlernen. Supereinfach. Die Grundlagen sind in fünf Minuten erlernt und werden schnell zur zweiten Natur. Und – genau wie die Beziehung zwischen CSS und CSS-Präprozessoren – können Sie so wenig oder so viel verwenden, wie Sie möchten.

Wenn Sie an Konventionen zum Schreiben von Klartext gewöhnt sind, sind Sie möglicherweise bereits mit einigen Markdown-Konventionen vertraut, z. B. Zahlen oder Bindestriche am Anfang eines Satzes, um eine Liste zu erstellen, Sternchen um ein Wort zur Hervorhebung und so weiter an. Wenn Sie beispielsweise etwas kursiv darstellen möchten, packen Sie es einfach in Sternchen wie *this* ein (im Gegensatz zu klobigerer HTML-Syntax wie <span>this</span> ).

Auf ähnliche Weise können Sie eine H1-Überschrift angeben, indem Sie Ihrer Zeile einfach ein „#“-Präfix hinzufügen (z. B. # Section Heading anstelle von <h1>Section Heading</h1> ).

Eine weitere großartige Verwendung zum Erlernen von Markdown, insbesondere für uns Softwareentwickler, besteht darin, es für die Dokumentation in Quellcode-Repositorys zu verwenden. Die meisten Repos enthalten eine README.md -Datei ( .md ist die Standarderweiterung für eine Markdown-Datei). Github hat beispielsweise einen eigenen „Github-flavored Markdown“, der zusätzliche Funktionen speziell für die Entwicklungsdokumentation hinzufügt. Dies kann gegenüber dem Schreiben dieser Dokumentation in HTML sicherlich Zeit sparen.

Nehmen wir als einfaches Beispiel an, Sie möchten das folgende Snippet in Ihre Dokumentation aufnehmen:

<h2 style=color:#3863a0;font-size:1.5em;font-weight:600;margin-top:2em;margin-bottom:1em;line-height:1.3em;>Initiieren von Plugins</h2>

Initiieren pluginName in Ihrem Container mit jQuery wie folgt:

$(function() { $('#container').pluginName(); }); Unter Verwendung der ID unseres Containers können wir pluginName mit der jQuery-Methode .pluginName() initiieren.

Hier ist ein Vergleich, wie dies in HTML vs. Markdown erfolgen würde:

Für weitere Hilfe beim Einstieg gibt es online viele Markdown-Tutorials, die Ihnen helfen, sich auf den neuesten Stand zu bringen, einschließlich einer Markdown-Übersicht von John Gruber (Markdowns Ersteller) sowie eines Online-Markdown-Tutorials.

Markdown-Parser und -Tools

Sobald Sie Ihren Artikel in Markdown geschrieben haben, benötigen Sie eine App, um die Syntax in HTML zu analysieren. Es gibt ein paar großartige, die kostenlos sind, darunter:

• StackEdit – browserbasierter Markdown-Editor, der einige Synchronisierungsoptionen mit beliebten Diensten wie Google Drive und Dropbox bietet
• Online Kramdown Editor – ein weiterer browserbasierter Markdown-Editor mit einer extrem einfachen Benutzeroberfläche
• Mou – der beste Mac-basierte Markdown-Writer, der mir als geekigere Option für Entwickler begegnet ist; jede Menge Funktionen und kostenlos (während der Beta-Phase) [das habe ich verwendet, um diesen Artikel zu schreiben]
• MarkdownPad - großartiger Markdown-Editor für Windows
• Texte - ein netter plattformübergreifender (Mac und Windows) Editor; Exporte in mehrere Formate wie PDF, .doc und ePub

Einige große Plattformen haben die Verwendung von Markdown in ihren Editoren bereits eingeführt (oder zumindest zugelassen) für diejenigen, die es verwenden möchten. Bei anderen wie WordPress, Evernote und Google Docs ist die native Unterstützung (zum Zeitpunkt des Schreibens dieses Artikels) noch nicht integriert, aber benutzerdefinierte Lösungen wurden von Drittanbietern eingeführt. Diese schließen ein:

• Die beliebte neue Blogging-Plattform Ghost verwendet Markdown für seinen Inhaltseditor, um das Online-Schreiben zu rationalisieren.
• Für WordPress unterstützt das Jetpack-Plugin jetzt offiziell Markdown, das Sie unter Einstellungen > Diskussion aktivieren können, wenn Sie das Plugin verwenden. Oder Sie könnten ein Plugin wie WP-Markdown verwenden, das Ihren Post-Markdown-Inhalt in HTML und zurück in Markdown konvertiert, wenn Sie ihn bearbeiten müssen.
• Für Evernote ermöglichen einige Markdown-Apps wie der Online-Editor Markable oder der Mac-Editor Byword den Export und die Veröffentlichung direkt in Notizen. Oder wenn Sie die Evernote-Web-App direkt verwenden möchten, können Sie eine Browsererweiterung namens Markdown Here verwenden, die eine ausgewählte, in Markdown geschriebene Notiz mit einem Klick auf die Schaltfläche in der Symbolleiste in formatierten Text umwandelt.
• Google Docs unterstützt Markdown noch nicht nativ, aber einige Editoren (z. B. StackEdit) exportieren/synchronisieren direkt mit Drive.

Die Nachteile

Mit großer Einfachheit gehen natürlich auch Einschränkungen einher. Wie ich bereits erklärt habe, wurde Markdown nicht für komplexe Textverarbeitungsaufgaben geschrieben, die erweiterte Formatierungsfunktionen erfordern. Wenn Sie das brauchen, ist Markdown nicht das richtige Werkzeug.

Aber für Entwickler, die ein Benutzerhandbuch oder eine technische Dokumentation oder einen technischen Bericht schreiben müssen, bietet Markdown eine nahezu perfekte Balance zwischen Einfachheit und den Funktionen, die Sie benötigen.

Der vielleicht größte Nachteil – insbesondere für uns Ingenieure, die Änderungskontroll-Junkies sind – ist die Unfähigkeit, in Markdown kollaborativ zu arbeiten und Änderungen zu verfolgen (eine bemerkenswerte Ausnahme davon ist jedoch das StackEdit-Plug-in für Google Docs). Und natürlich kann man mit minimalem Aufwand einfach über ein Git-Repository an einem Markdown-Dokument zusammenarbeiten und erhält dadurch die gesamte Änderungsverfolgung und Zusammenarbeit, die man normalerweise benötigt.

Fazit

Ist das Erlernen von Markdown also für jeden etwas? Natürlich nicht. Kein Werkzeug ist es jemals.

Aber wenn Sie ein Softwareentwickler sind, könnte es genau das Schreibwerkzeug sein, nach dem Sie gesucht haben. Wenn Sie es also noch nicht ausprobiert haben, sollten Sie es wirklich ausprobieren.