Markdown

LFP Docs unterstützt alle Template-Sprachen, die Eleventy anbietet. Es wird allerdings empfohlen, Markdown für das Verfassen von Inhalten für Dokumentationsseiten zu verwenden, um von dessen Einfachheit und Ergonomie zu profitieren.

Eine Seite mit minimal erforderlichem Umfang würde folgendermaßen aussehen:

---
title: Beispieldokument
---
Das ist Beispieltext, in **Markdown** geschrieben.

## Das ist eine Überschrift

Das ist mehr Text. Mit einer [internen Verknüpfung](/example/page/).

Überschriften

Überschriften stellen sich in Markdown als Zeile dar, die mit einer bis maximal sechs #, ähnlich den sechs Überschriftenebenen von HTML, starten.

Der Seitentitel wird in LFP Docs als Wert in title im Frontmatter gespeichert, es wird also empfohlen, im Fließtext nur Überschriften der Ebene zwei oder höher zu nutzen (wie im obigen Beispiel zu sehen).

Überschriften erhalten automatisch generierte IDs, über die sie referenziert werden können:

---
title: Beispieldokument
---
## Eine Überschrift

Eine [Verknüpfung](#eine-ueberschrift) zu einer Überschrift.

Im allgemeinen werden Überschriften in den Kebab-Case übersetzt, wobei Bindestriche Leer- und andere Sonderzeichen ersetzen. Wenn camelCase in der Überschrift verwendet wird, wird das Wort vor dem Binnenmajuskel getrennt, ein Bindestrich eingefügt und alles klein geschrieben; camelCase wird also zu camel-case. Für weitere Sonderfälle empfiehlt es sich, Verknüpfungen während der Entwicklung auf ihre Funktionalität zu überprüfen.

Verlinkungen

Bei Verlinkungen zwischen Markdown-Dokumenten, sollten die Pfade stets relativ zum in der Konfiguration festgelegten Output-Verzeichnis angegeben werden (alternativ kann der Permalink der Seite im Frontmatter gesetzt werden).

Automatische Konvertierung von Input- zu Outputpfaden wird derzeit nicht unterstützt, allerdings steht hierfür ein Plugin zur Verfügung; die Kompatibilität mit LFP Docs wurde nicht getestet.

Shortcodes

Shortcodes sind einfache Befehle, die mit Funktionen oder Makros einer Programmiersprache vergleichbar sind, dabei aber einfach in Markdown-Dokumenten eingesetzt werden können: sie akzeptieren üblicherweise textbasierten Input und geben HTML-Elemente zurück, die auf der Seite dargestellt werden können.

Einige Shortcodes werden von LFP Docs zur Verfügung gestellt (nachfolgend aufgelistet), es steht dem Anwender jedoch frei, auch eigene Shortcodes zu verfassen.

• Badge
• Codeblock
• Details
• Example
• Table of Contents

Standardmäßige Erweiterungen

Der Umfang des von Eleventy genutzte Markdownprozessor, markdown-it, ist standardmäßig gering; allerdings lässt sich markdown-it nach Bedarf sehr einfach um Funktionalitäten erweitern. Einige Erweiterungen bündelt LFP Docs als Plugin.

GFM-Hinweise

Für Angaben und wichtige Hinweise bieten sich GFM-Hinweise an. Sie können wie folgt in Markdown genutzt werden:

::: important
This is an important section.
:::

::: caution "Eigene Beschriftung"
Ein Hinweis mit eigener Beschriftung. Dabei die den Beschriftungstext in Anführungszeichen setzen.
:::

::: note
:::

::: tip
:::

::: new
:::

Das ausgegebene Markup sieht schließlich so aus:

Multi-lingual support for alert labels is currently only allowed on a site-wide level (see configuration for lang and i18n). Consider setting a custom label for translating on a per-page basis.

Mehrsprachige Hinweisbeschriftungen sind derzeit lediglich mittles globaler Konfiguration möglich (siehe Konfigurationen für lang und i18n für weitere Informationen). Eine andere Möglichkeit ist, eine benutzerdefinierte Beschriftung zu nutzen (siehe oben).

Attribute

Das Plugin markdown-it-attrs ermöglicht das Hinzufügen von HTML-Attributen zu einzelnen Markdown-Elementen.

Der Einsatz lohnt sich besonders bei mehreren gleichlautenden Überschriften auf einer Seite, zu denen manuell verlinkt werden soll:

### Überschrift {#individuelle-id}

-> <h3 id="individuelle-id"><a href="#individuelle-id">Überschrift</a></h3>

Fußnoten

Fußnoten sind via markdown-it-footnote verfügbar und können wie folgt eingesetzt werden:

Das ist Bespieltext.^[Und das hier ist eine inline-Fußnote.]

Mehr Text.[^1]

[^1]: Und eine weitere Fußnote.

Fußnoten werden automatisch an das Ende des Textinhalts der Seite angehängt.

Markdown erweitern

Weil Eleventy und damit LFP Docs auf markdown-it als Markdownprozessor setzen, kann der Prozessor einfach erweitert werden; indem die Instanz in der Konfigurationsdatei von Eleventy angepasst wird:

// other imports
import mdExtension from 'markdown-it-your-extension';

export default function (eleventyConfig) {
  // weitere Konfiguration
  eleventyConfig.amendLibrary('md', mdLib => {
    mdLib.use(mdExtension),
    // Platz für Plugin-Optionen, falls unterstützt
  });
  // weitere Konfiguration
}

Weitere unterstützte Sprachen

Neben Markdown unterstützt LFP Docs die folgenden Sprachen:

• einfaches HTML (nützlich, um spezifische Seiten zu erstellen, z. B. eine Landing Page)
• JavaScript (als 11ty.js)
• Liquid
• Nunjucks

Auf der Übersichtsseite von Eleventy finden sich mehr Informationen. Die Sprache kann den benötigten Eigenschaften entsprechend genutzt werden, und es ist ebenso möglich, verschiedene Sprachen für verschiedene Dokumente zu nutzen.