Autor: Markus Möhler
Version: 1.1.0
Stand: 22.05.2013
Diese Version des Dokuments enthält nun die gesamte Markdown Spezifikation, ist aber sicher noch nicht fehlerfrei.
Ich freue mich sehr über Kommentare, Anregungen und Meinungen, diese bitte zunächst an markdown_syntax@nordcode.de, eine Kommentarfunktion füge ich noch hinzu.
Markus.
Die Auszeichnungssprache Markdown wurde von John Gruber (erstes Foto) und Aaron Swartz (zweites Foto) entworfen, um formatierte Texte in einem unformatierten Textformat einfach und intuitiv schreiben und lesen zu können.
So entspricht zum Beispiel der Einschluss in Sterne einem *hervorgehobenen* Wort und ein > am Anfang einer Zeile leitet ein Zitat ein. So, wie man es bei reinen Text-Emails gewohnt ist.
Ein weiterer Teil der Markdownidee ist es, den mit Markdown ausgezeichneten Text über ein Programm nach HTML konvertieren zu können. Obwohl Markdown explizit nicht als HTML-Ersatz gedacht ist, soll es doch einen Teil der HTML-Syntax lesbarer codieren - Markdown sei ein Schreibformat, so Gruber, HTML hingegen ein Satzformat (im Sinne des Setzens, des Gestaltens einer Webseite).
Markdown’s syntax is intended for one purpose: to be used as a format for writing for the web.
John Gruber
Wichtigstes Kriterium ist also die gute Lesbarkeit und Verständlichkeit des Quelltextes. Markdown soll so einfach wie möglich zu lesen und so einfach wie möglich zu schreiben sein. Daran haben sich auch die Weiterentwicklungen der Markdown Syntax zu orientieren.
Aus meiner Sicht ist Markdown vor allem aus einem anderen, sich allerdings mit der Idee von Gruber und Swartz deutlich überschneidenden Grund faszinierend:
Es abstrahiert Textformatierungen so, dass sie sowohl intuitiv für Menschen lesbar und verstehbar sind und damit nierderschwellig einfach hingeschrieben werden können - gleichzeitig aber können sie auch von einer Maschine gut interpretiert und übersetzt werden.
Damit werden Texte unabhängig von den Textverarbeitungsprogrammen, mit denen sie geschrieben sind. Unabhängig von den Systemen, auf denen sie geschrieben sind. Und unabhängig eben auch von einer späteren Darstellung, die auf die aktuelle Situation des Lesers abgestimmt werden, und so die Lesbarkeit und Nützlichkeit der Texte noch einmal deutlich erhöhen kann.
In diesem Sinne ist Markdown kein Schreibformat für das Web, sondern eines, dessen alternative Darstellungsformen bereits vom Design her unbestimmt sind (oder sein sollten).
In diesem Sinne erweitert beispielsweise Fletcher Penney mit MultiMarkdown die Markdown Syntax um LaTeX Spezifika, wie Formelsatz, Metadaten, bibliographische Informationen und auch sonstige Elemente, die eher für den Drucksatz relevant sind als für das Web.
Wenn man jetzt argumentiert, dass eine BibTeX-Unterstützung so wie MultiMarkdown sie bietet, nicht oder nur schwer in HTML Verwendung finden kann und sie somit nicht allgemein genug sei, um in Markdown aufgenommen zu werden, dann muss man auch sagen, dass HTML-Blöcke, die bereits Teil der Markdown Syntax sind, auch nur sehr schwer in LaTeX verwendet werden können.
Der Mime-Typ eines Markdown-Dokuemts ist bis auf weiteres text/x-markdown und ein Markdown Dokument ist immer in UTF-8 codiert.
Bis zum Beweis des Gegenteils gilt:
Ein Markdown Dokument besteht neben dem reinen Text aus Blöcken und Bereichen, denen Stile zugewiesen werden können. Hierbei beziehen sich Blockstile grundsätzlich auf ganz Absätze, Bereichsstile hingegen auf Wörter oder sogar nur Teile von Wörtern.
Grundsätzlich können Blöcke sowohl andere Blöcke (sog. innere Blöcke) als auch Bereiche beinhalten. Bereiche können ihrerseits nur Bereiche beinhalten, dann heißt der umgebende Bereich äußerer Bereich und der eingeschlossene innerer Bereich.
In der Regel wird bei verschachtelten Blöcken der an weitesten äußere Block durch ein Symbol an Anfang einer Zeile eingeleitet. Denkt man sich dieses Symbol nun als gelöscht, dann wird der nächstfolgende Block wiederum durch ein Symbol am Anfang der Zeile eingeleitet usw.
Die auf die erste Zeile folgenden Zeilen setzen i.d.R. die über ihnen geöffneten Blöcke fort, indem sie dieselben oder analoge Zeichen wie in der ersten Zeile verwenden. Durch Einrückungen wird die Zugehörigkeit zu einem inneren Block verdeutlicht, wobei grundsätzlich jede weitere Einrückung der nächsttieferen Verschachtelungsebene entspricht.
Hierbei besteht eine Einrückung aus einem Tab oder vier Leerzeichen. Steht vor einem Tab jedoch ein Symbol, ist ggf. ein weiterer Tab nötig, um eine Einrückung zu erreichen.
Wird ein innerer Block fortgesetzt, dann werden dadurch auch alle äußeren Blöcke fortgesetzt.
Ein Block wird dadurch beendet, dass er nicht fortgesetzt wird. Insbesondere wird ein innerer Block dadurch beendet, dass ein äußerer fortgesetzt wird.
Es ist üblich, aber i.d.R. nicht notwendig, dass Blöcke der obersten Verschachtelungsebene durch Leerzeilen voneinander abgesetzt werden.
Innerhalb von Blöcken werden Bereiche durch Symbole voneinander abgegrenzt.
Beispielsweise ist bei *fett* der Stern das Symbol und der Text "fett" ist der Bereich.
Zur Übersetzung einiger Begriffe siehe bitte unten unter Übersetzungen Deutsch / Englisch
Im Markdown Quelltext wird ein Zeilenumbruch durch ein oder eine Folge von Zeilenumbruchzeichen (CR, LF usw.) markiert. In einem Texteditor sind Zeilenumbrüche normalerweise nicht als Zeichen sichtbar, sondern daran zu erkennen, dass an ihnen die Zeile umbricht.
Im Markdown Quelltext ist eine Zeile ein Stück Text, das von zwei Zeilenumbrüchen umschlossen ist, oder das zwischen dem Anfang des Dokuments und einem Zeilenumbruch bzw. einem Zeilenumbruch und dem Ende des Dokuments steht.
Eine Leerzeile ist im Markdown Quelltext eine Zeile, die entweder gar nichts enthält (das entspricht zwei aufeinanderfolgenden Zeilenumbrüchen), höchstens aber aus Leerzeichen und Tabs besteht.
Beschreibung:
Um im Zieldokument einen Zeilenumbruch auszulösen, müssen an das Ende einer Textzeile zwei oder mehr Leerzeichen angehängt werden.
Besonderheit
Ein Zeilenumbruch im Markdown Dokument allein löst keinen Zeilenumbruch im Zieldokument aus.
Beispiel:
Markdown (in Zeile 2 sind zwei Lerrzeichen angehängt):
Zeile 1
Zeile 2
Zeile 3
Ergebnis:
Zeile 1
Zeile 2
Zeile 3
Quelle:
Markdown (Gruber)
Beschreibung:
Um im Zieldokument einen Absatzwechsel zwischen zwei Textzeilen auszulösen, müssen zwischen ihnen eine oder mehrere Leerzeilen eingefügt werden.
Besonderheit
Leerzeilen erzeugen in Markdown nicht nur einen Absatzwechsel im Zieldokument, sie sind auch ein wichtiges Strukturelement: Leerzeilen grenzen nämlich Markdown-Blöcke voneinander ab, siehe Grundlagen und Begriffe.
Beispiel:
Markdown (die Zeilen 1 und 2 sind von einer Leerzeile getrennt):
Zeile 1
--Leerzeile--
Zeile 2
Ergebnis:
Zeile 1
Zeile 2
Quelle:
Markdown (Gruber)
Da Markdown entworfen wurde, um daraus HTML zu generieren, wurde auch die Möglichkeit geschaffen, HTML-Elemente innerhalb eines Textes zu verwenden.
HTML kann dabei innerhalb eines bestehenden Blocks einen HTML-Bereich aufspannen (siehe HMTL im Text) oder es beschreibt einen eigenen Block (siehe HTML-Block). Diese beiden Varianten werden unterschiedlich ausgewertet.
Gemeinsam ist ihnen aber, dass HTML-Tags den Konvertierungsprozess von Markdown nach HTML so durchlaufen sollen, dass das Ergebnis anschließend von einem HTML-Parser, zum Beispiel einem Browser, weiterhin als HTML erkannt wird.
Beschreibung:
Steht ein Text zwischen den Zeichen kleiner als (<) und größer als (>), wird der Text zuzüglich der beiden einschließenden Zeichen als HTML-Bereich interpretiert.
Wird das Dokument nach HTML konvertiert, dann wird ein HTML-Bereich in das Zieldokument mit eingearbeitet; wird hingegen ein Dokument anderen Typs generiert, dann wird ein HTML-Bereich möglicherweise ganz oder teilweise ignoriert.
Besonderheiten
Beispiel:
Markdown: Dieser Text verwendet <b> HTML zum *Fettsetzen* </b>.
Ergebnis: Dieser Text verwendet HTML zum Fettsetzen .
Quelle:
Markdown (Gruber)
Kommentar
Meine Definition weicht von der John Grubers ab, der 1.) den gesamten Textabschnitt von ersten öffnenden HTML-Tag bis zum entsprechenden schließenden Tag als HTML-Bereich sieht. Entsprechend erlaubt er 2.) die Anwendung von Markdown Syntax innerhalb eines HTML-Bereichs, er erlaubt also innere Bereiche. In meiner Definition darf nur der HTML-Body einen inneren Bereich haben. Zum dritten, also 3.) schränkt John Gruber die erlaubten Tags auf Inline-Level-Elemente ein (siehe hier (engl.) für eine Liste der Inline-Level-Elemente). Im Gegensatz dazu stehen die Block-Level-Elemente (siehe hier (engl.) für eine Liste der Block-Level-Elemente).
Mir erscheinen innere Bereiche innerhalb der eigentlichen Tags nicht als sinnvoll, da Tags den technischen Bereich von HTML beschreiben, lediglich im HTML-Body machen sie meines Erachtens Sinn, daher betachte ich meine Definition als eine Konkretisierung der Punkte 1.) und 2.).
Zu 3.) meine ich folgendes:
Zwischen < und > kann sich ein Inline-Level-Tag befinden, ein Block-Level-Tag oder etwas sonstiges. Werden Block-Level-Tags und sonstige Tags für die Darstellung in HTML escaped, so dass sie auch in gerendertem HTML als Text dargestellt werden, dann erscheint mir das wie eine misslungene Form der Fehlermeldung, denn nicht jeder wird genau wissen, welche Tags nun als valides HTML interpretiert werden und welche nicht. Erst nach der Konvertierung würde klar, welche Tags den Markdown-Filter passieren und welche nicht.
Wenn der Benutzer nun aber HTML-Tags benutzt, dann vermutlich mit der Absicht, dass sie von einem HTML-Parser auch als HTML interpretiert werden sollen, und ich denke man sollte besser annehmen, dass ein Benutzer, der HTML in Markdown verwendet, auch weiss was er tut. Dies gilt insbesondere für sonstige Tags, also dem dann in den Markdown Parser integrierten Mini-HTML-Parser unbekannte Elemente. Ich sehe keinen Grund, warum hier der Absicht des Benutzers entgegengewirkt werden sollte.
Beschreibung:
Beginnt ein Block mit einem HTML-Bereich (siehe HTML im Text), d.h. er beginnt mit einem kleiner als (<), dann folgt ein Text und darauf ein größer als (>), alles in dem selben Block, dann ist der gesamte Block ein HTML-Block.
Anders als beim HTML-Bereich, wird innerhalb eines HTML-Blocks keinerlei Markdown-Syntax angewendet, auch nicht im HTML-Body.
Besonderheit:
Wird ein Markdown Dokument, das einen HTML-Block enthält, nach HTML konvertiert, so wird der HTML-Block hierbei nicht von <p>-Tags umschlossen (wie sonst bei Blöcken üblich).
Beispiel:
Markdown:
Dies ist ein einfacher Absatz
<table>
<tr>
<td>Foo und *Bar*</td>
</tr>
</table>
Dies ist wieder ein einfacher Absatz.
Ergebnis:
Dies ist ein einfacher Absatz
| Foo und *Bar* |
Dies ist wieder ein einfacher Absatz.
Quelle
Markdown (Gruber)
Kommentar
Ich schlage vor, abweichend von John Gruber, nicht auf explizite Block-Level-Elemente zu prüfen - und zwar mit derselben Argumentation wie in dem Kommentar zu HTML im Text, um nämlich einen Mini-HTML-Parser innerhalb eines Markdown-Parsers zu vermeiden und den Nutzer nicht ohne Grund in seinen Möglichkeiten zu beschränken.
Um meinen Standpunkt zu illustrieren: Bestehende Implementierungen sind in diesem Punkt ziemlich unvorhersehbar, man prüfe das gern selbst nach. Oft werden manche Block-Level-Elemente als solche erkannt und akzeptiert, andere hingegen nicht, die Auswahlkriterien bleiben im Dunkeln und manchmal laufen sogar das Syntax-Highlighting und die HTML-Generierung auseinander.
In allen Quelltexten gibt es definitionsgemäß funktionstragende Zeichen. Will man diese Zeichen in seinen Texten verwenden, dann muss man sicherstellen, dass bei der Konvertierung des Quelltextes diese Zeichen nicht versehentlich als funktionstragend interpretiert werden. Hierfür stellt man zum Beispiel dem gewünschten Zeichen ein weiteres Zeichen (Escape-Zeichen) voran, dass diese Funktion erfüllt. Das gewünschte Zeichen ist damit escaped.
Bei Markdown wird beispielsweise ein Kursiv-Bereich durch einen Stern eingeleitet. Möchte ich den Stern als Zeichen in einem Text verwenden, kann ich ihm einen umgekehrten Schrägstrich (Backslash) voranstellen: \*
Bei Markdown gibt es viele Möglichkeiten, Zeichen zu escapen; explizit durch das Hinzufügen eines Escape-Zeichens oder implizit durch den Bereich oder den Block, in dem sich das Zeichen befindet.
Durch die Nähe zu HTML wurden zudem von John Gruber Regeln für das Escapen von Zeichen nicht nur bezüglich der Markdown-Syntax, sondern auch bezüglich der HTML-Syntax eingeführt. Soll aus einem Markdown-Dokument zudem nicht nur HTML-Generiert werdem sondern auch z.B. LaTeX, dann muss es außerdem noch Escape-Möglichkeiten für LaTeX geben.
Beschreibung:
Wird einem Zeichen ein umgekehrter Schrägstrich (Backslash) vorangestellt, dann wird dieses Zeichen als solches ausgegeben. Dies gilt für funktionstragende Zeichen der Markdown-Syntax selbst, aber auch für solcher aller Dokumenttypen, die aus Markdown generiert werden können, z.B. HTML oder LaTeX.
So kann man zum Beispiel \< verwenden, um das Zeichen < auch in HTML als solches auszugeben.
Besonderheiten
Beispiel:
Markdown: Dieses \<tag\> und dieses \# werden zu lesbaren Zeichen konvertiert.
Ergebnis: Dieses <tag> und dieses # werden zu lesbaren Zeichen konvertiert.
Quelle
Markdown (Gruber)
Kommentar
John Guber beschränkt den Backslash Escape auf die Zeichen: umgekehrer Schrägstrich \ , Gravis ` , Stern * , Unterstrich _ , geschweifte Klammern { und } , eckige Klammern [ und ] , Klammern ( und ) , Doppelkreuz # , Plus + , Minus - , Ausrufungszeichen ! und Punkt .
Ich sehe keinen Grund dafür, nicht alle Zeichen escapebar zu machen, und dem dokumemntierten Willen des Benutzers, der ein Backslash vor ein Zeichen stellt, entgegenzuwirken.
Viele Markdown Implementerungen machen das bereits jetzt so oder erlauben zumindest mehr escapefähige Zeichen als die aufgelisteten.
Beschreibung:
Zeichen können als HTML-Entitäten codiert werden, um ihre Ausgabe in allen Dokumententypen zu erreichen. Hierzu können folgende Notationen verwendet werden:
&#nummer; mit nummer als dezimal beschriebene Unicode-Nummer des auszugebenden Zeichens.&#xnummer; mit nummer als hexadezimal beschriebene Unicode-Nummer des auszugebenden Zeichens.&name; mit name als Name der Entität wie für HTML 4.0 spezifiziert, siehe siehe hier für eine weitere Auflistung der Zeichen.Generell führt ein einleitendes & und ein abschließendes ; innerhalb eines Blocks dazu, dass der Text dazwischen als HTML-Entitäten-Bereich erkannt wird, solange er keine Leerzeichen enthält. Auch dann, wenn weder eine Interpretation als name, noch als nummer erfolgreich sind - in diesem Fehlerfall wird entweder die gesamte Entität incl. & und ; als Text ausgegeben (z.B. bei HTML, für den Fall, dass der Browser damit noch etwas anfangen kann) oder es wird ein Fragezeichen ? ausgegeben (bei Dokumententypen, die HTML-Entitäten von sich aus nicht auswerten können).
Besonderheiten:
Beispiel:
Markdown: Ich habe ein ♥ für HTML-Entitäten.
Ergebnis: Ich habe ein ♥ für HTML-Entitäten.
Quelle
Markdown (Gruber)
Kommentar
Das Verhalten im Fehlerfall wurde von John Gruber nicht beschrieben, das habe ich so hinzugefügt, wie es mir sinnvoll erscheint.
Beschreibung:
Innerhalb von Markdown-Text werden die funktionstragenden Zeichen des Zieldokuments automatisch escaped. Dies wird gemacht, damit zum einen der Schreibfluss nicht unnötig gestört wird, aber vor allem, damit man zum Verwenden von Markdown das Zielformat nicht kennen muss.
Für die Generierung von HTML bedeutet das beispielsweise, dass die Zeichen < und & automatisch nach > bzw. & konvertiert werden, insbesondere auch in URLs.
Besonderheit:
Das escapen von HTML Entitäten - hier wäre das voranstehende & betroffen - hat natürlich Vorrang vor dem automatischen Escape. Generell gesprochen hat das Parsen von Markdown an sich Vorrang vor dem automatischen Escape.
Beispiel:
Markdown: Dies & das.
Ergebnis (HTML Code): Dies > das.
Quelle
Markdown (Gruber)
Kommentar
John Gruber beschreibt nur den automatischen Escape für HTML - verwendet man aber Markdown auch zu Generierung anderer Zielformate, dann setzt die Ausdehnung der Regel zum automatischen Escape die Absicht Grubers nur fort.
Bereichsstile zeichnen sich durch folgende Eigenschaften aus:
Beschreibung:
Steht ein Text zwischen zwei Sternen oder zwei Unterstrichen, wird er kursiv gesetzt.
Besonderheiten:
Beispiele:
Markdown: Dieser Text ist *teilweise kursiv* gesetzt, auf _zwei verschiedene_ Arten.
Ergebnis: Dieser Text ist teilweise kursiv gesetzt, auf zwei verschiedene Arten.
Markdown: Manche Wörter sollen als Kursiv nur *teil*ausgezeichnet werden, auch hierfür wird ein * oder ein _ verwendet.
Ergebnis: Manche Wörter sollen als Kursiv nur teilausgezeichnet werden, auch hierfür wird ein * oder ein _ verwendet.
Quelle:
Markdown (Gruber)
Beschreibung:
Steht ein Text zwischen zwei Doppelsternen oder zwei doppelten Unterstrichen, wird er fett gesetzt.
Besonderheiten:
Beispiele:
Markdown: Dieser Text ist **teilweise fett** gesetzt, auf __zwei verschiedene__ Arten.
Ergebnis: Dieser Text ist teilweise fett gesetzt, auf zwei verschiedene Arten.
Markdown: Manche Wörter sollen als fett nur **teil**ausgezeichnet werden.
Ergebnis: Manche Wörter sollen als fett nur teilausgezeichnet werden.
Quelle:
Markdown (Gruber)
Beschreibung:
Steht ein Text zwischen zwei Gravis (frz. accent grave, engl. backtick quotes), wird er als Code gesetzt, das bedeutet in einer Schriftart, deren Zeichen alle gleich breit sind (nichtproportional) und manchmal auch noch anderweitig gesondert hervorgehoben. Dieses Markdownsymbol ist dafür gedacht, Quellcode auszuzeichnen.
Hierfür werden bei einer Darstellung als HTML die Zeichen Kaufmannsund (&), kleiner als (<) und größer als (>) auch immer als HTML-Entitäten übertragen. Das ist zwar im normalen Textfluss oft auch so, allerdings entsteht z.B. aus > innerhalb eines einfachen Textes bei der HTML-Generierung ein >-Zeichen, während daraus > wird, sollte es von Gravis-Symbolen umschlossen sein.
Als Alternative zu einfachen Gravis können auch doppelte verwendet werden. In diesem Fall werden einfache Gravis innerhalb des Code-Bereichs als Gravis-Zeichen ausgegeben. Zudem darf - anders als beispielsweise bei den Markdownsymbolen für Fett und Kursiv - ein doppeltes Gravis von Leerzeichen umgeben sein, ohne seine Funktion zu verlieren.
Die Besonderheiten von Code rühren daher, dass gewünscht ist, Quellcode - auch HTML-Quellcode - in einen Code-Bereich mittels kopieren/einfügen einsetzen zu können.
Beispiele
Markdown: Die Funktion `printf()` ist einfacher Code, aber mit `` `foo` `` können auch einfache Gravis als Code dargestellt werden.
Ergebnis: Die Funktion printf() ist einfacher Code, aber mit `foo` können auch einfache Gravis als Code dargestellt werden.
Quelle:
Markdown (Gruber)
Um einen Link (Hyperlink) zu setzen, gibt es vier verschiedene Möglichkeiten:
Beschreibung:
Ein Link wird über das folgende Format vollständig beschrieben:
[zu verlinkender Text](http://url.de/ "Optionaler Titel")
Oder genauer:
Der zu verlinkende Text steht in eckigen Klammern [ ], auf die unmittelbar runde Klammern folgen, die die URL enthalten. Optional kann noch ein Leerzeichen gefolgt von einem Bildtitel in einfachen ' oder in doppelten " Anführungszeichen hinter die URL gesetzt werden (noch innerhalb der runden Klammern).
Beispiel:
Markdown:
Bitte klicken Sie [hier](http://www.nordcode.de/).
Ergebnis:
Bitte klicken Sie hier.
Quelle:
Markdown (Gruber)
Beschreibung:
Soll ein Link mittels Referenz gesetzt werden, wird folgendes Format verwendet:
[zu verlinkender Text][referenzname]
Der zu verlinkende Text steht hierbei in eckigen Klammern [ ], unmittelbar gefolgt von dem Namen der Referenzvariablen, ebenfalls in eckigen Klammern. Zwischen der schließenden Klammer des zu verlinkenden Textes und der öffnenden Klammer der Referenzvariablen darf ein Leerzeichen stehen.
Siehe den Abschnitt Referenzen für Details.
Beispiel:
Markdown:
Oder Sie klicken [hier][nordcode].
[...]
[nordcode]: http://www.nordcode.de
Ergebnis:
Oder Sie klicken hier. Quelle:
Markdown (Gruber)
Beschreibung:
Analog zu den Links mit expliziter Referenz, können sie einen Link setzen, bei dem der zu verlinkenden Text gleichzeitig auch als Name der Referenzvariablen verwendet wird:
[zu verlinkender Text][]
Auf den zu verlinkenden Text in eckigen Klammern [ ] folgt ein optionales Leerzeichen und darauf eine öffnende und eine schließende eckige Klammer.
Beispiel:
Markdown:
Dies sind die Seiten von [Nordcode][].
[...]
[nordcode]: http://www.nordcode.de
Ergebnis:
Dies sind die Seiten von Nordcode.
Quelle:
Markdown (Gruber)
Beschreibung:
Zu guter Letzt gibt es noch Links, deren zu verlinkender Text die URL selbst ist, sogenannte automatische Links. Hierzu wird die URL in spitze Klammern < > gesetzt:
<http://url.de/>
Das funktioniert auch bei Emailadressen:
<email@url.de>
Besonderheit:
Als Spamschutz wurde von John Gruber spezifiziert, dass das HTML-Ergebnis einer Emailadresse diese aus zufälligen HTML-Entitäten zusammensetzen soll.
So kann der automatische Adresslink von <email@url.de> in HTML wie folgt aussehen:
<a href="mailto:email@url.de">email@url.de</a>
Beispiel:
Markdown:
Bitte besuchen Sie <http://www.nordcode.de>.
Ergebnis:
Bitte besuchen Sie http://www.nordcode.de.
Quelle:
Markdown (Gruber)
Beschreibung:
Um ein Bild zu platzieren, kann man die URL des Bildes entweder unmittelbar bei der Bilddeklaration mitangeben, oder man kann per Referenz darauf verweisen.
Gibt man sie unmittelbar an, lautet das Format zur Platzierung eines Bildes im Groben:
Und genauer:
Soll ein Bild mittel Referenz platziert werden, lautet das Format:
![alternativer Text][referenzname]
Und genauer:
Um die hierbei notwendige Referenz zu beschreiben, siehe den Abschnitt über Referenzen.
Besonderheit
Die Bild-URL verweist auf ein Bildformat, das nach dem Konvertieren von dem Ziel-Dateiformat interpretiert werden kann.
Beispiel:
Markdown:
![Spitzbergen]: http://www.nordcode.de/resources/spitzbergen.jpg
Quelle:
Markdown (Gruber)
Kommentar:
Derzeit gibt es noch keine Möglichkeit, die Ausrichtung oder Größe des Bildes zu beeinflussen.
Beschreibung:
Eine Referenz speichert eine URL und zusätzlich optional einen Titeltext in einer Variablen (Referenzvariable). Ein Link oder ein Bild können so, anstatt diese Daten unmittelbar anzugeben, auf diese Variable referenzieren.
Das Format zur Definition einer Referenzvariablen ist im Groben:
[referenzname]: http://url.de/ "Optionaler Titel"
Und genauer:
Eine Referenz muss in einer eigenen Zeile beginnen, es darf aber zwischen der URL und dem Titeltext ein Umbruch und darauffolgend Leerzeichen oder Tabs eingefügt werden.
Besonderheiten
Beispiele
Markdown:
[nordcode]: http://www.nordcode.de
Quelle:
Markdown (Gruber)
Beschreibung:
Um eine horizontale Trennlinie (entsprechend dem <hr /> Tag in HTML) im Markdown zu beschreiben, müssen an den Anfang einer Zeile drei oder mehr Minuszeichen ---, drei oder mehr Sterne *** oder drei oder mehr Unterstriche ___ gesetzt werden.
Zwischen den einzelnen Zeichen dürfen Leerzeichen stehen, die Zeile darf insgesamt aber nur gleichartige Zeichen und Leerzeichen enthalten.
Besonderheit:
Werden zur Bezeichnung einer Trennlinie Minuszeichen verwendet, dann muss die darüberliegende Zeile eine Leerzeile sein, da sie sonst zu einer Überschrift wird, siehe Überschriften.
Beispiel:
Markdown:
* * *
Ergebnis (HTML Code):
<hr />
Quelle:
Markdown (Gruber)
Beschreibung:
Ein Codeblock ist ein Absatz, der als Code gesetzt ist (siehe Code im Text für Details dazu, was das bedeutet).
Um einen Codeblock als solchen auszuzeichnen, muss jeder seiner Zeilen eine Einrückung (vier Leerzeichen oder ein Tab) vorangestellt werden.
Ein Codeblock endet, wenn der auf ihn folgenden Zeile keine Einrückung vorangestellt ist.
Besonderheiten:
& wird zu einer HTML-Entität escaped.Beispiel:
Markdown:
Dies ist eine Textzeile.
100 print "Wer dies liest ist doof!"
200 goto 100
Und dies ist wieder Text.
Ergebnis (HTML Code):
<p>Dies ist eine Textzeile.</p>
<pre><code>100 print "Wer dies liest ist doof!"
200 goto 100
</code></pre>
<p>Und dies ist wieder Text.</p>
Quelle:
Markdown (Gruber)
Beschreibung:
Überschriften sind auf sechs Ebenen möglich, wobei die Ebene 1 die oberste Ebene mit der größten Überschrift darstellt.
Um eine Überschrift zu erzeugen, gibt es zwei verschiedene Möglichkeiten:
Möglichkeit 1: Wird eine Zeile mit Gleichheitszeichen = oder Minuszeichen - unterstrichen, dann wird aus ihr eine Überschrift der Ebene 1 oder 2, genauer:
Besteht eine Markdown-Zeile ausschließlich aus Gleichheitszeichen oder ausschließlich aus Minuszeichen und zudem mindestens aus drei Stück der jeweiligen Art, dann wird aus der darüberliegenden Zeile eine Überschrift - im Falle der Gleichheitszeichen eine der Ebene 1, im Falle der Minuszeichen eine der Ebene 2.
Möglichkeit 2: Beginnt eine Markdown-Zeile mit einem oder mehreren Doppelkreuzen #, dann wird der darauffolgende Text dieser Zeile zu einer Überschrift.
Die Anzahl der Doppelkreuze bestimmt direkt die Ebene der Überschrift, drei Doppelkreuze erzeugen bespielsweise eine Überschrift der Ebene 3.
Optional können in derselben Zeile, nach dem Überschriftentext, noch eine beliebige Anzahl von Doppelkreuzen angefügt werden, ohne als Text ausgegeben zu werden. Üblicherweise sind dies genauso viele wie am Anfang der Zeile, um den Tag wieder zu schließen.
Besonderheiten:
Beispiel:
Markdown:
Dies ist eine Überschrift der Ebene 1
=====================================
## Und dies eine der Ebene 2 ##
Quelle:
Markdown (Gruber)
Kommentar:
Die Überschriften auf den verschiedenen Ebenen können auch verwendet werden, um aus ihnen beispielsweise ein Inhaltsverzeichnis zu generieren. In diesem Fall wäre es bei einer Generierung nach HTML beispielsweise sinnvoll, die generierten Überschriften auch noch mit Link-Ankern zu versehen.
Tritt eine Überschrift als innerer Block auf, dann ist es vermutlich nicht sinnvoll, sie mit in das Inhalsverzeichnis zu übernehmen.
Beschreibung:
Ein Zitatblock (engl. blockquote) ist im Ergebnis ein eingerückter und/oder durch Anführungszeichen besonders ausgezeichneter Textabsatz.
Beginnt eine Markdown Zeile mit einem größer als Zeichen >, dann wird die aktuelle Zeile und alle ihr nachfolgenden Zeilen solange als Zitatblock begriffen, bis dieser durch eine Leerzeile abgeschlossen wird.
Optional kann auch jede Zeile oder beliebig viele Zeilen des Zitatblocks mit einem > beginnen, ohne das dieses als Zeichen ausgegeben wird.
Die Idee hinter dem Zitatblock ist die des Zitats einer Email, auf die geantwortet wird: Es soll möglich sein, ein gesamtes Markdown-Dokument durch das voranstellen eines > zu jeder Zeile zu einem Zitat zu machen.
Besonderheit:
Ein Zitatblock erlaubt innere Blöcke, wie Aufzählungen oder Überschriften.
Beispiel:
Markdown:
> Dies ist ein
> Zitat.
Ergebnis:
Dies ist ein Zitat.
Quelle:
Markdown (Gruber)
Beschreibung:
In Markdown können sowohl Aufzählungslisten, deren Einträge durch Aufzählungszeichen (z.B. Spiegelstriche) dargestellt werden, wie auch nummerierte Listen beschrieben werden, deren Einträge eine durchgehende Numerierung 1, 2, .. erhalten.
Eine Liste wird dadurch beschrieben, dass ihre Einträge durch Symbole ausgezeichnet werden:
Für Aufzählungslisten sind das die Symbole Stern *, Minus - und Plus +, die alternativ und sogar abwechselnd verwendet werden können. Für nummerierte Listen ist das eine Zahl, auf die ein Punkt . folgt.
Beginnt eine Zeile mit null bis drei Leerzeichen, folgt dann ein Aufzählungssymbol und darauf ein bis drei Leerzeichen oder ein Tab, dann wird diese Zeile als erster Eintrag einer Liste begriffen.
Geschieht dasselbe auch bei der darauffolgenden Zeile, dann gilt diese als zweiter Listeneintrag usw.
Eine Liste ist beendet, wenn sie nicht mehr durch weitere Listeneinträge verlängert wird. Ein Listeneintrag ist beendet, wenn entweder ein neuer Listeneintrag beginnt, oder wenn ihm eine Leerzeile folgt.
Besonderheiten:
Auch wenn zwei aufeinanderfolgende Listeneinträge durch eine Leerzeilen voneinander getrennt sind, gelten sie als Einträge derselben Liste, werden aber als verschiedene Absätze abgebildet.
Soll ein Listeneintrag über meherere Markdown-Zeilen beschrieben werden, so kann entweder ein einfacher Zeilenumbruch verwendet werden oder ein Zeilenumbruch mit darauffolgender Einrückung (Tab oder vier Leerzeichen), beides ist gleichwertig.
Soll es mehere Absätze innerhalb eines Listeneintrags geben, dann muss zunächst eine Leerzeile eingefügt werden und darauf folgend eine Einrückung.
Nummerierte Listen werden nach der Generierung immer in einer Aufzählung 1, 2, .. abgebildet, egal welche Zahlen in Markdown verwendet werden.
Die Zahlen einer nummerierten Liste dürfen maximal drei Ziffern haben - da auf sie ein Punkt folgt, würden sie mit mehr als vier Zeichen die Einrückungsbreite überschreiten.
Innerhalb von Listen können innere Blöcke beschrieben werden, siehe Grundlagen und Begriffe für Details hierzu.
Beispiele:
Markdown:
* Eins
* Zwei
* Drei
Ergebnis:
Markdown:
5. Eins
7. Zwei
<Leerzeile>
9. Drei
Ergebnis:
Zwei
Quelle:
Markdown (Gruber)
Kommentar:
Listen sind in der Definition von John Gruber ziemlich komplizierte Gebilde. Insofern ist das letzte Wort hier vermutlich noch nicht gesprochen, beispielsweise was die maximale Anzahl der Ziffern des Symbols für eine nummerierte Liste betrifft.
Ich schreibe diesen Text in Deutsch und übersetze ihn dann später ins Englische. Meine Quellen sind allerdings komplett in Englisch, so dass ich bereits beim Schreiben dieses Textes Schlüsselwörter habe übersetzen müssen.
Um das Verständnis und die Internetsuche nach diesen Schlüsselwörtern zu erleichtern, liste ich hier einige der Wörter auf, die ich sinngemäß und nicht notwendigerweise langenscheidtkonform verwende.
Markdown-Symbol / Symbol - delimiter
John Gruber benutzt den Begriff delimiter oder element um die für Mardown typischen Zeichen zu benennen, die einen zu gestaltenden Bereich begrenzen, ohne selbst dargestellt zu werden, z.B. den * bei *kursiv*.
Ich übersetze das mit Markdown-Symbol oder Symbol.
Bereich - span
Mit Bereich im allgemeinen oder Code-Bereich, Kursiv-Bereich im speziellen, ist der Textabschnitt gemeint, der von Markdownsymbolen begrenzt wird.
Beispiel:
Gruber: The backtick delimiters surrounding a code span may include spaces — one after the opening, one before the closing.
Die Markdownsymbole (Gravis), die einen Code-Bereich umgeben, dürfen Leerzeichen enthalten - eines nach dem Öffnen und eines vor dem Schließen.
Fotos:
Foto von John Gruber, Autor: George Del Barrio, dieses Foto steht unter einer Creative Commons Lizenz (CC BY-SA 3.0).
Foto von Aaron Swartz bei einem Creative Commons Event, Autor: Fred Benenson, dieses Foto steht unter einer Creative Commons Lizenz (CC BY 2.0).
Die generelle Idee zu Markdown und die ersten Richtlinien zur Syntax stammen von John Gruber:
John Gruber: Markdown Syntax (engl.)
Version 1.1.0 vom 22.05.2013
Inhaltsverzeichnis hinzugefügt.
Version 1.0.0 vom 17.05.2013
Codeblock, Referenzen und Metadaten, Links und Horizontale Trennlinie hinzugefügt, damit ist die Spezifikation von Markdown vollständig (wenn auch sicher nicht fehlerfrei).
Version 0.6.0 vom 16.05.2013
Überschriften, Zitatblöcke und Listen hinzugefügt, Grundlagen und Begriffe überarbeitet.
Version 0.5.0 vom 15.05.2013
Automatischer Escape, Absätze und Zeilenumbrüche hinzugefügt.
Version 0.4.0 vom 13.05.2013
Escapen von Zeichen, HTML Block und ein Beispiel für HTML im Text hinzugefügt.
Version 0.3.0 vom 09.05.2013
Grundlagen und Begriffe, HTML Spezifika und HTML im Text hinzugefügt, das Dokument ist jetzt Markdown Spezifikation übertitelt.
Version 0.2.0 vom 08.05.2013
Die erste veröffentlichte Version, unfertig, work in prrogress, ich freue mich über Kommentare und Anregungen.