Markdown-Funktionen
DocStatic verwendet Markdown als Hauptformat für die Erstellung von Inhalten. Sie können es in zehn Minuten lernen. Das ist jedoch nicht notwendig, da das CMS eine vollständige Rich-Text-Bearbeitungsumgebung für Metadaten, Markdown und React-Komponenten bietet.
Einfaches strukturiertes Erstellen
Themen in DocStatic bestehen aus drei Teilen:
- Metadaten (im YAML-Format)
- Inhalt (in Markdown)
- Vordefinierte React-Komponenten.
Das CMS sorgt dafür, dass Metadaten und Markdown konsistent verwendet werden, während die React-Komponenten einen einheitlichen Stil und Unterstützung für Funktionen zur Wiederverwendung von Inhalten bieten. Sie müssen selbst keinen JSX-Code hinzufügen, da die Komponenten bereits global verfügbar sind.
Standardfunktionen
Zu den Markdown-Funktionen gehören:
- Fett-, Code-, Kursiv- und Durchstreichungszeichen.
- Aufzählungslisten und nummerierte Listen.
- Code-Blöcke.
- Überschriftenebenen (1 bis 6).
- Horizontale Linien.
- Bilder.
- Links.
- Zitate.
- Einfache Tabellen.
All diese Funktionen können direkt über die Rich-Text-Symbolleiste im CMS ausgewählt werden.
Dazu fügt Docusaurus noch Folgendes hinzu:
- Hinweise
- Details (erweiterbare Inhalte)
- Doc-Card-Listen
- Registerkarten
DocStatic erweitert dies noch um:
- Code-Schnipsel (aus Dateien)
- Kommentare
- Bedingter Text
- Kontext-Hilfe-Links
- Diagramme
- Abbildungen
- Fußnoten
- Glossarbegriffe
- Mathematische Gleichungen
- Snippets
- Variablen
Front Matter
Front Matter wird verwendet, um Metadaten zu Ihrer Markdown-Datei hinzuzufügen. Es befindet sich ganz oben in der Datei, umgeben von drei Bindestrichen ---. Inhalts-Plugins können ihr eigenes Front-Matter-Schema haben. DocStatic verwendet Front Matter für:
- Bedingungen (für bedingten Text)
- Beschreibungen
- Slugs (feste Pfade)
- Taxonomie-Tags
- Titel
- Workflow-Status
Details
- Wählen Sie Details aus der Liste Einbetten.
- Bearbeiten Sie die Komponente.
- Geben Sie ihr eine Zusammenfassung.
- Geben Sie die Details ein.
Beispiel:
Toggle me.
Dies ist der detaillierte Inhalt.
Sie können hier Markdown verwenden, einschließlich fettgedrucktem und kursivem Text sowie Inline-Links.
Dokumentenkartenlisten
Dokumentenkartenlisten werden automatisch für Kategorien im Inhaltsverzeichnis generiert. Sie können sie jedoch auch manuell zu einem Thema hinzufügen.
- Wählen Sie Dokumentenkartenliste aus der Liste Einbetten aus.
- Geben Sie einen Titel ein.
Weitere Informationen finden Sie unter Markdown-Funktionen in der Docusarus-Dokumentation.
Beispiel:
📄️ MDX and React
DocStatic bietet integrierte Unterstützung für MDX, wodurch Sie JSX in Ihren Markdown-Dateien schreiben und als React-Komponenten rendern können. Wenn Sie JSX jedoch direkt in Ihren Themen hinzufügen, kann das CMS diese nicht im Rich-Text-Editor anzeigen.
📄️ Tabs
Mit der Komponente Tabs können Sie Ihrem Thema Inhalte mit Registerkarten hinzufügen.
📄️ Code blocks and snippets
DocStatic bietet zwei Möglichkeiten, Code in Ihre Dokumentation einzufügen. Beide unterstützen Syntaxhervorhebung.
📄️ Admonitions
Mit der Komponente Hinweise können Sie formatierte Hinweise hinzufügen.
📄️ Headings and table of contents
Im CMS können Sie die Ebene Absatz oder Überschrift (von 1 bis 6) auswählen.
📄️ Assets
Manchmal möchten Sie direkt aus Themen heraus auf Assets (z. B. DOCX-Dateien, Bilder usw.) verlinken. DocStatic verwaltet dies über den Ordner „static/“.
📄️ Markdown links
Es gibt zwei Möglichkeiten, einen Link zu einer anderen Seite hinzuzufügen: über einen URL-Pfad oder einen Dateipfad.
📄️ MDX plugins
MDX verfügt über ein integriertes Plugin-System, mit dem Sie die Art und Weise anpassen können, wie Markdown-Dateien geparst und in JSX umgewandelt werden. Wenn Sie jedoch das Verhalten von Markdown ändern, müssen Sie diese Änderungen auch im CMS berücksichtigen.
📄️ Math equations
Mathematische Gleichungen können mit KaTeX dargestellt werden.
📄️ Diagrams
Diagramme können mit Mermaid in einem Code-Block gerendert werden.
📄️ Head metadata
DocStatic setzt automatisch nützliche Seiten-Metadaten in `, und ` für Sie.
📄️ Comments
Mit der Komponente Kommentar können Sie Kommentare hinzufügen, die im CMS sichtbar sind, aber nicht auf der gerenderten Seite, auch nicht im Rohquellcode.
📄️ Conditional text
Mit der Komponente Bedingter Text können Sie Inhalte in eine Reihe von Bedingungen einbinden, die festlegen, wann sie angezeigt werden sollen:
📄️ Context-sensitive help
„Kontextsensitive Hilfe ist eine Art von
📄️ Figures
(kein Quellinhalt)
📄️ Footnotes
Es gibt eine Erweiterung zu Markdown, die Fußnoten bereitstellt, aber ihre Implementierung ist nicht konsistent und trennt den Inhalt von der Nummer. Zum Beispiel:
📄️ Glossary terms
Mit der Komponente Glossarbegriff können Sie einen Schlüssel eingeben, der einem lokalisierten Begriff und einer Beschreibung zugeordnet ist. Der Begriff wird unterstrichen angezeigt. Wenn Sie den Mauszeiger über den Begriff bewegen, wird der Hilfe-Cursor angezeigt, und wenn Sie mit der Maus darüber fahren, wird die Beschreibung als Tooltip angezeigt. Auf Touchscreen-Geräten wird durch Antippen des Begriffs eine Popup-Definition angezeigt.
📄️ Snippets
Mit der Komponente Snippet können Sie Inhalte in Ihrer Dokumentation wiederverwenden. Ein Snippet ist ein Inhaltsblock, der in ein oder mehrere Themen eingefügt werden kann. Wenn Sie Änderungen am Snippet vornehmen, werden diese überall dort übernommen, wo das Snippet verwendet wird. Dies kann besonders für Standardtexte nützlich sein. Snippets haben ihre eigene Sammlung im CMS und sind in einem separaten Teil des Repositorys enthalten.
📄️ Variable sets
Mit der Komponente „Variable“ können Sie eine lokalisierte Variable in Ihren Text einfügen.