Struktur reicht weiter als Konventionen
## Installation ist in allen CommonMark-Renderern als ATX-Überschrift der Stufe zwei erkennbar. Installation gefolgt von Bindestrichen ist eine Überschrift der Setext-Ebene zwei. Bei dieser Vereinbarung geht es um die Dokumentenstruktur.
Das Fragment nach dem # einer URL gehört zur HTML-Navigation. Ein Renderer kann die Überschrift verkleinern, Satzzeichen entfernen und Leerzeichen durch Bindestriche ersetzen, aber die Kernspezifikation von Markdown erfordert diesen Algorithmus nicht. Die schwierigen Fälle zeigen die Lücke:
| Sichtbare Überschriften | Fragen, die ein Gastgeber beantworten muss |
|---|---|
Café & crème | Unicode beibehalten, Akzente zerlegen oder das Original kodieren? |
Install! und Install | Überleben Unterschiede in der Interpunktion das Schlagen überleben? |
Drei Exemplare von Usage | Ist das Suffix -1, -2, _2 oder etwas anderes? |
Zwei konforme Markdown-Tools können unterschiedlich antworten, da das Parsen von Überschriften und die automatische ID-Generierung separate Aufgaben sind.
Analysieren Sie Blöcke, bevor Sie Hashes scannen
Eine Zeile, die mit ## beginnt, ist nicht unbedingt eine Dokumentüberschrift. Innerhalb eines eingezäunten Codeblocks handelt es sich um wörtlichen Beispielinhalt. Text mit vier Leerzeichen ist ebenfalls Code. Aus diesem Grund hat die Blockphase von CommonMark Vorrang: Entscheiden Sie, wo sich Code und andere Blöcke befinden, und interpretieren Sie dann die Überschriftensyntax in der verbleibenden Struktur.
Vor dem Weiterlesen
Eine README-Datei enthält `## Delete everything` in einem Beispiel für eine eingezäunte Shell. Sollte ein Inhaltsverzeichnis-Scanner es verlinken?
Nein. Ein Scanner muss eingezäunten und eingerückten Code verfolgen, bevor er Kursmarkierungen interpretiert. Andernfalls werden Dokumentationsbeispiele zu falschen Navigationseinträgen.
Der Markdown-Inhaltsverzeichnis-Ersteller folgt dieser Reihenfolge und veröffentlicht seine unterstützte Teilmenge. Es bezeichnet sich selbst nicht als universellen Renderer für jede Erweiterung.
Machen Sie beide Seiten des Links explizit
Ein verfasstes <a id="install"></a> liefert das Ziel, anstatt einen Host zu bitten, eines zu erfinden. Eine generierte Liste kann genau auf #install verweisen und doppelte IDs können aufgelöst werden, bevor das Dokument das Tool verlässt.
Das verbessert die Portabilität, ist aber keine Zauberei. Rohes HTML wird von CommonMark zugelassen und kann dennoch durch den Sanitiser einer Website entfernt werden. Der ehrliche Arbeitsablauf besteht darin, die Zielrichtlinie zu kennen, explizite IDs zu generieren, wenn dies zulässig ist, und eine Vorschau eines veröffentlichten Dokuments anzuzeigen, bevor die Konvention überall angewendet wird.
Der generierte Text sollte überprüfbar und ersetzbar sein
Ein Generator benötigt Eigentumsgrenzen. Anfangs- und Endkommentare identifizieren die Tabelle, die später ersetzt werden kann. Markierte Ankerlinien identifizieren die Ziele, die es besitzt. Nicht markierter HTML-Code bleibt Eigentum des Autors. Dadurch wird die Regeneration idempotent, ohne dass „Alte Tabelle entfernen“ zu einer umfassenden Löschheuristik wird.
Der Text Diff Maker stellt die zweite Hälfte dieser Disziplin bereit. Vergleichen Sie Quelle und Ausgabe mit drei Kontextzeilen, um die Tabelle und Anker an Ort und Stelle zu sehen, oder mit Nullkontext, um nur eingefügte Zeilen zu isolieren. Ein einfaches Zeilentool ist zum Sortieren von Inhalten nützlich, behält jedoch nicht die Überschriftenhierarchie eines Dokuments bei und sollte nicht als Markdown-Parser verwendet werden.
Fragen
Definiert CommonMark Überschriftenanker im GitHub-Stil?
Nein. CommonMark definiert Überschriften und Links, während automatische IDs im GitHub-Stil eine Renderer-Konvention sind. Ein anderer Host kann ein anderes Fragment aus derselben sichtbaren Überschrift erzeugen.
Sind explizite HTML-Anker in Markdown gültig?
CommonMark erlaubt rohe HTML-Blöcke und Inline-HTML, und ein HTML-`id` kann ein Fragmentziel sein. Ein Veröffentlichungsdienst kann diesen HTML-Code dennoch als Produkt oder Sicherheitsrichtlinie bereinigen.
Wie kann ich überprüfen, was ein Generator geändert hat?
Vergleichen Sie den ursprünglichen und den generierten Markdown Zeile für Zeile. Ein einheitliches Diff macht jede eingefügte Tabellenzeile, jeden Marker und jeden Anker sichtbar, ohne dass Sie den unveränderten Text erneut lesen müssen.