This page (revision-7) was last changed on 29-Jul-2025 21:11 by Markus Monderkamp 

This page was created on 13-Jun-2025 17:25 by ThomasBayen

Only authorized users are allowed to rename pages.

Only authorized users are allowed to delete pages.

Page revision history

Version Date Modified Size Author Changes ... Change note
7 29-Jul-2025 21:11 10 KB Markus Monderkamp to previous Typo bereinigt
6 16-Jun-2025 12:30 10 KB ThomasBayen to previous | to last Ghostwriter Markdown Editor
5 16-Jun-2025 10:55 9 KB ThomasBayen to previous | to last Nachtrag zum Marktext-Editor
4 14-Jun-2025 20:11 9 KB ThomasBayen to previous | to last
3 14-Jun-2025 11:58 9 KB ThomasBayen to previous | to last Personalisierung eine Docusaurus-Projekts
2 13-Jun-2025 18:17 4 KB ThomasBayen to previous | to last Für den Anfang habe ich so mit Docusaurus meine ersten Schritte gemacht
1 13-Jun-2025 17:25 1 KB ThomasBayen to last

Page References

Incoming links Outgoing links
Docusaurus
Docusaurus

Version management

Difference between version and

View first change
!!! Docusaurus

[Docusaurus|http://docusaurus.io][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

Wie im Installations-Befehl angegeben, wurde das "classic" template installiert. Das ist eie Art klienes Beispiel-Projekt, das einen Dateibaum mit ein paar sinnvollen Dateien vorgibt. Leider gibt es wohl bisher von Docusaurus her kein anderes sinnvoll einsetzbares Template. Also bleiben wir dabei und passen das an (siehe unten für ein Beispiel).

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 run 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 Editor

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.

Nachtrag: Leider hat Marktext die unangenehme Eigenschaft, das man ungespeicherten Inhalt aus Tabs verliert, wenn man ein anderes Tab öffnet (oder so, manchmal sogar gespeicherten, glaube ich. Ich habe noch nicht ganz verstanden, was den Bug triggert). Also etwas Vorsicht. Bei der Gelegenheit habe ich gesehen, das das Projekt seit ca. 2022 nicht mehr gut gepflegt aussieht. Für mein Problem gibt es immerhin schon ein Ticket seit April 2022 (https://github.com/marktext/marktext/issues/3232).


!! Ghostwriter


Von diesem Editor ([Ghostwriter|https://ghostwriter.kde.org/de/]) gibt es ein Debian-Paket, so das er sich einfacher installiert als der Marktext. Leider bietet er keine so schöne Ansicht des Dateibaums am linken Rand. Dafür werden bereits geöffnete Dateien angezeigt - da kann man in einem größeren Kapit auch ganz gut mit arbeiten.


!!! Beispielprojekt

Mit der normalen Installation erzeugt man ein Beispiel-Projekt aus dem "classic"-Template. Dieses habe ich nun angepasst für ein eigenes Projekt. Ich möchte hier beispielhaft aufzeigen, was man da alles anpassen kann. Dabei versuche ich, zu erklären, was man dabei über die Funktionsweise von Docusaurus lernen kann.

;TSX:TSX-Dateien enthalten eine Typescript-basierte Auszeichnungssprache, um React-Komponenten zu definieren. (Puh! Komplizierter Satz, wenn man das alles nicht kennt). Typescript ist eine typisierte Variante von Javascript und React ist ein Framework, um Komponenten für Weboberflächen zu programmieren. Das bedeutet, das man hier kleinere Änderungen im HTML vornehmen kann, aber auch aufregendere Sachen, wenn man sich etwas mit Typescript und React Komponenten auskennt. Insbesondere kann man solche bereits vorhandenen Komponenten einbinden.

Auf der Eingangsseite sind drei grosse Bilder mit Texten darunter. Diese sind als ein Beispiel für eine Komponente ausgeführt (Diese heisst HomepageFeatures). Man kann in src/conponents/HomepageFeatures sehen, wie diese Komponente aufgebaut ist.


!! index.tsx

Die Eingangsseite selbst findet sich in src/pages/index.tsx.

Ich bin jetzt in ebendiese index.tsx Datei gegangen und habe folgendes geändert:

Den Eintrag {{<HomepageFeatures />}} habe ich komplett entfernt. Das brauche ich nicht. In dieser Funktion Home() habe ich auch die Description und den Titel angepasst.

Den Text auf dem Linkbutton in der Funktion HomepageHeader() "Docusaurus Tutorial" habe ich ersetzt durch die Bezeichnung meiner eigenen Anleitung.


!! docusaurus.config.ts

Diese Datei befindet sich im Hauptverzeichnis und enthält die grundlegenden Einstellungen.

Siehe https://docusaurus.io/docs/api/docusaurus-config, https://docusaurus.io/docs/configuration

* {{title}} habe ich entsprechend angepasst
* {{tagline}} ist eine einzeilige Beschreibung meines Projektes, die später auf der Homepage unterhalb des Titels steht
* Den Link zum {{favicon}} habe ich gelassen, aber dann später die entsprechende Datei mit meinem eigenen Logo überschrieben.

* {{URL}} und {{BaseUrl}} brauchth man erst, wenn man die Seite irgendwohin hochlädt. Das sehe ich mir später an.

* {{internationalization}} habe ich auf {{de}} geändert, weil meine Texte deutsch sein sollen. Bisher weiss ich aber noch nicht genau, was das praktisch bedeutet.


* Die {{presets}} geben nur Einstellungen für die docs- und blog Funktionalität vor. Sie auszukommentieren, wenn man einen Teil nicht möchte, macht hier keinen Sinn (Das kommt später).
* Für die {{editUrl}} von {{docs}} und {{blog}} habe ich beide Zeilen auskommentiert. Das bedeutet, das ich auch in der Developer-Version auf der angezeigten Webseite keinen Link mehr zum editieren der Seite habe. (Wie oben geschrieben, funktioniert das nur, wenn ich das Projekt auf Github hoste und bearbeiten möchte)

* in {{themeConfig}} kann ich jetzt wirklich einstellen, was ich auf der Webseite anzeigen möchte.
** {{image}} habe ich auskommentiert, weil ich (noch) keine Social Media Card für mein eigenes Projekt habe.
** Das zweite und dritte Item (Blog und GitHub) habe ich auskommentiert. Die brauche ich nicht.

* Im {{footer}} steht auch eine ganze Menge Zeug, das ich nicht brauche. Das habe ich auch auskommentiert.
* den gesamten Bereich mit {{title: 'Community'}}.
* Alle Items aus dem Bereich mit {{title: 'More'}}
* Dafür habe ich "More" in "Links" umbenannt und hier einen Link eingefügt, der zu einer Webseite führt, die mit meinem Projekt zusammenpasst. (ähnlich einfach wäre es auch, sowas oben in der Titelzeile einzufügen.)

!! static/img

In diesem Verzeichnis befinden sich statische Grafiken. Im Prinzip kann man dort alles löschen, wenn man keine Dinosaurier irgendwo sehen möchte.

* Ich habe ein kleines, quadratisches Logo meines Projektes im png-Format nach src/img/favicon.ico kopiert.
* Ich habe ein Logo meines Projektes als png ebenfalls hierher kopiert. Das das auch benutzt wird, habe ich in der docusaurus.config.ts angegeben.


Mit diesen Änderungen ist es mir ganz einfach und schnell gelungen, die Webseite für meine Zwecke anzupassen und zu personalisieren. Jetzt kann ich mich darauf konzentrieren, die Dokumentation zu schreiben, um die es ja eigentlich geht.
This page (revision-7) was last changed on 29-Jul-2025 21:11 by Markus Monderkamp  Top