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-cli wird über npm, den Paketmanager von Node.js, geladen. Aus den Ubuntu-Paketquellen kommen nur Node.js und npm.
  • Ohne globale Installation: docsify-cli wird nicht mit sudo npm install -g systemweit installiert, sondern bei Bedarf mit npx gestartet. 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.html lä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

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.

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.

Autor: Thorsten · Installationsanleitungen für Ubuntu

Alle Anleitungen ohne Gewähr. Befehle mit sudo verändern das System – vorher lesen, dann ausführen.