Hinweis: Diese Inhalte wurden mit Unterstützung von Künstlicher Intelligenz erstellt und redaktionell überprüft (Transparenzhinweis gemäß Art. 50 EU AI Act).
Docsify
Hinweis: Diese Inhalte wurden mit Unterstützung von Künstlicher Intelligenz erstellt und redaktionell überprüft (Transparenzhinweis gemäß Art. 50 EU AI Act).
Docsify macht aus einem Ordner mit Markdown-Dateien eine Dokumentations-Website mit Seitenleiste und Suche. Es erzeugt dabei keine HTML-Dateien: Eine einzige index.html lädt die Markdown-Dateien erst im Browser und stellt sie dort dar.
Vorbemerkungen
- Kein apt-Paket: Docsify ist nicht in den Ubuntu-Paketquellen enthalten. Das Hilfsprogramm
docsify-cliwird übernpm, den Paketmanager von Node.js, geladen. Aus den Ubuntu-Paketquellen kommen nur Node.js und npm. - Ohne globale Installation:
docsify-cliwird nicht mitsudo npm install -gsystemweit installiert, sondern bei Bedarf mitnpxgestartet. Es wird nur zum Anlegen des Projekts und für die Vorschau gebraucht. - Kein Bauschritt: Anders als bei mdBook oder Hugo gibt es keinen Befehl, der die Website baut. Der Projektordner ist schon die fertige Website.
- Internet nötig: Die
index.htmllädt Docsify selbst, das Design und die Suche vom Dienst jsDelivr (cdn.jsdelivr.net). Beim Aufruf der Website überträgt der Browser dabei die IP-Adresse des Besuchers an jsDelivr. Wer das vermeiden will, muss die Dateien selbst auf dem Server ablegen. Das zeigt diese Anleitung nicht. - Version: Getestet mit Docsify 5.0.0 und docsify-cli 5.0.0 unter Node.js 22 aus Ubuntu 26.04. Beide brauchen Node.js 20.11 oder neuer.
- Port: Die Vorschau soll hier auf Port 3001 laufen. Der voreingestellte Port 3000 ist oft schon belegt, z. B. durch Martin.
Installation
1. Paketlisten aktualisieren
Damit apt die aktuellen Versionen von Node.js und npm kennt.
sudo apt update
2. Node.js und npm installieren
Node.js führt docsify-cli aus, npm lädt es herunter und bringt den Befehl npx mit. Sind beide schon vorhanden, meldet apt das nur.
sudo apt install nodejs npm
Prüfen: Die Ausgabe ist eine Versionsnummer ab v20.11, z. B. v22.22.1.
node --version
Hast du Node.js zusätzlich über den Versionsmanager nvm installiert, wird dessen Version angezeigt. Das ist in Ordnung, solange sie mindestens v20.11 ist.
Eine Dokumentation anlegen
3. Projekt erzeugen
npx lädt docsify-cli vorübergehend herunter und führt es aus. init legt den Ordner ~/meindocsify/docs an und schreibt drei Dateien hinein: index.html (die Seite, die Docsify startet), README.md (die Startseite) und .nojekyll (verhindert, dass GitHub Pages Dateien mit _ am Anfang weglässt).
npx docsify-cli init ~/meindocsify/docs
Die Frage Need to install the following packages: docsify-cli … Ok to proceed? (y) beantwortest du mit Enter.
Prüfen: Die Ausgabe enthält Initialization succeeded!.
4. In den Projektordner wechseln
Alle weiteren Befehle beziehen sich auf diesen Ordner.
cd ~/meindocsify
Prüfen: Die Ausgabe zeigt index.html und README.md.
ls docs
5. Docsify einstellen
In index.html stehen die Einstellungen im Block window.$docsify. Hier werden der Name der Website, die deutsche Sprache, die Seitenleiste und die Suche eingerichtet.
nano docs/index.html
Ersetze den ganzen Inhalt: Drücke Alt+\ (an den Anfang), Alt+A (Markierung beginnen), Alt+/ (ans Ende) und Strg+K (Markiertes löschen). Füge dann diesen Inhalt ein (Strg+Umschalt+V):
<!DOCTYPE html>
<html lang="de">
<head>
<meta charset="utf-8">
<title>Meine Dokumentation</title>
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@5/dist/themes/core.min.css">
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@5/dist/themes/addons/vue.min.css">
</head>
<body>
<div id="app"></div>
<script>
window.$docsify = {
name: 'Meine Dokumentation',
loadSidebar: true,
subMaxLevel: 2,
search: {
placeholder: 'Suchen …',
noData: 'Keine Treffer'
}
}
</script>
<script src="//cdn.jsdelivr.net/npm/docsify@5"></script>
<script src="//cdn.jsdelivr.net/npm/docsify@5/dist/plugins/search.min.js"></script>
</body>
</html>
name– steht oben in der Seitenleiste.loadSidebar: true– Docsify baut die Seitenleiste aus der Datei_sidebar.md(Schritt 8).subMaxLevel: 2– unter der geöffneten Seite zeigt die Seitenleiste zusätzlich deren Zwischenüberschriften (##).search– deutsche Texte für das Suchfeld. Die letzte<script>-Zeile lädt die Suche dazu.docsify@5– lädt immer die neueste Version 5.x.
Speichere mit Strg+O und Enter und beende nano mit Strg+X.
6. Startseite schreiben
README.md ist die Seite, die beim Aufruf der Website erscheint.
nano docs/README.md
Ersetze den englischen Beispieltext wie in Schritt 5 durch:
# Willkommen
Diese Dokumentation wurde mit **Docsify** erstellt.
Speichere mit Strg+O und Enter und beende nano mit Strg+X.
7. Eine zweite Seite anlegen
Jede weitere Markdown-Datei im Ordner docs wird eine eigene Seite.
nano docs/installation.md
Füge diesen Inhalt ein:
# Installation
## Voraussetzungen
Ein Rechner mit Ubuntu.
## Schritte
Erst installieren, dann starten.
Speichere mit Strg+O und Enter und beende nano mit Strg+X.
8. Seitenleiste anlegen
Ohne diese Datei zeigt die Seitenleiste nur die Überschriften der aktuellen Seite. Jede Zeile ist ein Link auf eine Seite. / steht für die Startseite.
nano docs/_sidebar.md
Füge diesen Inhalt ein:
- [Startseite](/)
- [Installation](installation.md)
Speichere mit Strg+O und Enter und beende nano mit Strg+X.
9. Vorschau starten
serve startet einen kleinen Webserver für den Ordner docs. -p 3001 wählt Port 3001. Der Server lädt die Seite im Browser neu, sobald du eine Datei speicherst.
npx docsify-cli serve docs -p 3001
Prüfen: Die Ausgabe enthält Listening at http://localhost:3001. Öffne http://localhost:3001 im Browser. Links stehen das Suchfeld „Suchen …“, „Meine Dokumentation“ und die beiden Seiten. Nach einem Klick auf „Installation“ erscheinen darunter „Voraussetzungen“ und „Schritte“.
Die Vorschau selbst ist nur vom eigenen Rechner aus erreichbar. Das automatische Neuladen läuft aber über Port 35729 und ist im ganzen Netzwerk offen. Starte die Vorschau deshalb nur in einem vertrauenswürdigen Netz und beende sie mit Strg+C, wenn du sie nicht mehr brauchst.
10. Website veröffentlichen
Einen Bauschritt gibt es nicht: Der Ordner docs ist die Website. Ihn kann jeder Webserver ausliefern, zum Beispiel wie in Statische Website mit nginx beschrieben. Kopiere dafür den Inhalt von docs in den Ordner der Website.
Die Seiten haben Adressen wie …/#/installation. Der Teil nach # wird nur im Browser ausgewertet, deshalb braucht der Webserver keine besonderen Einstellungen.
Ein Doppelklick auf index.html im Dateimanager reicht dagegen nicht: Der Browser öffnet die Datei dann ohne Webserver und darf die Markdown-Dateien nicht nachladen. Die Seite bleibt leer.
Aktualisieren
1. Docsify auf der Website
Durch docsify@5 in index.html lädt der Browser automatisch die neueste Version 5.x. Du musst dafür nichts tun. Für eine neue Hauptversion (z. B. Docsify 6) änderst du die Zahl in allen vier Zeilen mit docsify@5, nachdem du die Hinweise unter https://github.com/docsifyjs/docsify/releases gelesen hast.
2. docsify-cli
npx verwendet die Version, die es beim ersten Aufruf zwischengespeichert hat. Mit @latest lädt es die neueste Version.
npx docsify-cli@latest --version
Prüfen: Die Ausgabe zeigt die neue Versionsnummer, z. B. 5.0.0 oder höher.
Deinstallieren
1. Projektordner löschen
Das Projekt besteht nur aus den eigenen Dateien. Achtung: Damit sind auch alle Seiten der Dokumentation gelöscht. Wer sie behalten will, kopiert vorher den Ordner ~/meindocsify/docs.
rm -r ~/meindocsify
Prüfen: ls meldet, dass es den Ordner nicht gibt.
ls ~/meindocsify
2. npm-Zwischenspeicher leeren (optional)
npm bewahrt das vorübergehend geladene docsify-cli in ~/.npm auf. Dieser Befehl leert den ganzen Speicher. Das betrifft alle Node.js-Projekte, die ihre Pakete dann beim nächsten Mal wieder aus dem Internet laden.
npm cache clean --force
Node.js und npm bleiben installiert, weil andere Anleitungen sie ebenfalls verwenden.
Quellen und Lizenz
- Offizielle Dokumentation: https://docsify.js.org/
- Lizenz: Docsify steht unter der MIT.
Hinweis: Diese Inhalte wurden mit Unterstützung von Künstlicher Intelligenz erstellt und redaktionell überprüft (Transparenzhinweis gemäß Art. 50 EU AI Act).
Open Knowledge (Freies Wissen): Alle Texte stehen unter der freien Lizenz Creative Commons Namensnennung – Weitergabe unter gleichen Bedingungen 4.0 International (CC BY-SA 4.0) und können frei gelesen, geteilt und weiterverarbeitet werden.