!!! Docusaurus

[Docusaurus|http://docusuarus.io] ist eine Software, um einfach statische Webseiten aus simplen markdown-Dateien zu erstellen. Es arbeitet dabei wie eine Art sehr ausgefeilter Template-Generator.

Es basiert auf React und Node.js, ist also in Javascript bzw. Typescript geschrieben.

Es eignet sich insbesondere für Dokumentationen, weil es zu einem Verzeichnisbaum mit Kapiteln (als markdown-Dateien) automatisch eine Baumstruktur, ein Inhaltsverzeichnis, eine Suche, etc. generieren kann. Es gibt aber auch ein integriertes Blog, das auch sehr einfach aber dennoch leistungsfähig für normale Zwecke ist. Auf Grund der Fähigkeit, Plugins einzubinden, könnte es noch andere spannende Fähigkeiten geben, die ich aber noch nicht erforscht habe. Außerdem kann man anstatt markdown-Dateien eine erweiterte Version namens MDX benutzen, das auch aktive Javascript/React-Komponenten einbinden kann. Auch das habe ich aber bisher nicht getestet.

Man kann Docusaurus als Server laufen lassen, dann werden die Webseiten live erzeugt. Änderungen am Quelltext werden also augenblicklich umgesetzt. Man kann aber auch eine statische Version der Webseite erzeugen, die man dann irgendwo in einen Webspace kopiert und dort ohne weitere Bibliotheken oder Serverbedingungen veröffentlichen kann.

!! Installation

Tatsächlich habe ich eine Weile gebraucht, um zu verstehen, wie einfach das wirklich ist. ;-) Das liegt vielleicht auch daran, das meine Erfahrung mit Javascript, Node.js und npm gleich Null ist. Was aber ja schön ist, das hier zu dokumentieren, das man solche Erfahrung auch nicht braucht.

Die Doku auf https://docusaurus.io/docs/installation ist übrigens ziemlich gut und einfach zu verstehen, man muss sie nur auch richtig lesen. ;-)

Ich musste zwei Debian-Pakete installieren:

  aptitude install nodejs npm

Node.js ist eine Javascript-Bibliothek, die häufig (und also auch hier) benutzt wird. npm ist ein Paketmanager für Javascript Programme. Dieser enthält u.a. ein Tool namens npx, dem man einfach einen Paketnamen als Befehl mit Parametern übergibt, woraufhin das Paket selbstständig heruntergeladen, installiert und aktiviert wird. Praktisch bedeutet das, man geht in ein leeres Verzeichnis und installiert ein Beispieldokument mit 

  npx create-docusaurus@latest my-website classic --typescript


!! Was habe ich jetzt

Dann kann man schon im Verzeichnisbaum herumschauen. Möchte man eine Anleitung mit Kapiteln erzeugen, schaut man in die Beispiele in {{docs/}}. Die einzelnen Einträge für ein Blog stehen in {{blog/}} Die Konfiguration des Docusaurus ist in {{docusaurus.config.js}}

!! Erzeugen einer Webseite

Mit

  npm start

startet man einen lokalen Server, der die fertige Webseite auf http://localhost:3000 zugänglich macht. Diese Darstellung wird live erzeugt, was bedeutet, das Änderungen in mardown-Dateien im selben Moment auf der Webseite stehen. Mit

  npm build

erzeuge ich eine statische Version der Webseite in build/, die ich jetzt auf einen beliebigen Webserver kopieren kann.



!!! welchen Editor?

Tatsächlich war ich am Anfang etwas verwirrt, weil das in der Anleitung und den Demos immer so einfach aussieht, Dokumente zu bearbeiten. Das erschien fast so leicht wie ein Wiki. Ist aber nicht ganz so.

Zuerst mal zur Erklärung, was man da in der Anleitung sieht: Startet man den Development-Server von Docusaurus (wie oben angegeben), so erzeugt er unten auf der Seite einen Link zum Editieren der Seite (also des Quelltextes in markdown, d.h. einer *.md-Datei). Dieser Link führt dann allerdingsa zu einem github-Projekt (das man in {{docusaurus.config.js}} konfigurieren kann). Mehr macht der nicht. Wenn man ein öffentliches Projekt hat und dafür ein github-Repository angelegt hat und selber Schreibrechte darauf hat, ist das womöglich eine tolle Sache. Dann kann man direkt in Github *.md Dateien editieren und diese Änderungen direkt committen.

Wer den Aufwand nicht treiben möchte oder kann, ist allerdings darauf angewiesen, die markdown-Dateien mit dem Lieblings-Editor seiner Wahl zu bearbeiten. Das war dann meine Lösung.

Eine kurze Recherche, was es da für spezielle Editoren gibt (natürlich Open Source), brauchte mich auf Marktext. Ein solcher Editor erlaubt WYSIWYG-Eingaben. Aber natürlich tut es auch jeder emacs oder vi oder sonstwas. Markdown ist ja tatsächlich eine sehr einfache Sprache.


!! Marktext

Diesen Editor hat Gemini mir empfohlen. Ich habe mir von der Webseite das deb-Paket heruntergeladen und es installiert: [Marktext|https://github.com/marktext/marktext] Der Editor macht sehr schönes WYSIWYG und zeigt auch auf Wunsch einen Verzeichnisbaum links an, so das man eine Anleitung mit mehreren Kapiteln schon mit etwas ÜBersicht bearbeiten kann. Damit versuche ich es jetzt erstmal.