Erstellen und Anpassen einer Docusaurus-Seite (mit Blog-Funktion)

Für einfache Websites, Anwendungen und andere kleine Projekte entscheiden sich immer mehr Entwickler/innen für statische Website-Generatoren statt für WordPress oder andere Content-Management-Systeme (CMS). Statische Websites bieten eine einfache und effektive Möglichkeit, Websites und Anwendungen zu erstellen, die schnell, sicher und leicht zu pflegen sind.

Docusaurus ist ein solcher Generator für statische Websites, der sich in der Entwicklergemeinde immer größerer Beliebtheit erfreut.

In diesem Beitrag gehen wir näher auf die Vorteile von Docusaurus als Generator für statische Websites ein und erklären, warum er bei Entwicklern immer beliebter wird.

Was ist Docusaurus?

Docusaurus ist ein beliebter Generator für statische Websites, der React, eine der führenden JavaScript-Bibliotheken, als UI-Bibliothek für die Seitenerstellung verwendet. Wie andere Generatoren dieser Art ist er einfach einzurichten und zu ändern und – was am wichtigsten ist – er bietet dir alles, was du brauchst, um mit deiner statischen Website durchzustarten.

Das Besondere an Docusaurus ist jedoch, dass es dir hilft, eine Website zu erstellen und zu verwalten, bei der Inhalte eine zentrale Rolle spielen. Mit Docusaurus kannst du schnell und einfach eine vollständige Website mit Blogfunktion erstellen, die deine Inhalte von Anfang an in den Mittelpunkt stellt.

Da bei Docusaurus der Inhalt im Mittelpunkt steht, eignet es sich perfekt für die Erstellung von Dokumentationsseiten wie Wikis. Docusaurus nutzt außerdem Markdown, das ideal für die Zusammenarbeit und die Speicherung in einem Git-Repository ist. Darüber hinaus bietet Docusaurus viele tolle Funktionen wie i18n, Suche und benutzerdefinierte Themes, auf die wir später noch genauer eingehen werden.

Hier sind nur einige der herausragenden Funktionen, die Docusaurus zu einer guten Wahl machen:

• Entwickelt mit React
• Unterstützung für MDX v1
• Unterstützung für die Einbettung von React-Komponenten über Markdown
• Versionierung von Dokumenten
• Kompatibilität mit Git, Crowdin und anderen Übersetzungsmanagern für die Übersetzung von Dokumenten und die Massen- oder Einzelverteilung

Wer nutzt Docusaurus?

Docusaurus wurde von Facebook entwickelt. Daher ist es nicht verwunderlich, dass es derzeit von vielen großen Marken und Unternehmen im Internet genutzt wird.

Hier sind nur einige der größten Marken, die Docusaurus heute nutzen (und bald werden es noch mehr sein, da die Popularität von Docusaurus weiter wächst):

• Algolia DocSearch
• Jest
• React Native
• Supabase

Und jeden Tag kommen weitere hinzu.

So installierst du Docusaurus

Docusaurus ist sehr einfach zu installieren und benötigt nur wenige Minuten. In diesem Tutorial erstellen wir eine Dokumentationsseite mit einem Blog und passen das Aussehen der Website an.

Und jetzt kommt das Coolste daran: Wir werden weniger als eine Stunde brauchen, um alles einzurichten.

Lass uns loslegen!

Anforderungen

Docusarus benötigt Node.js 16.14 oder neuer. Es handelt sich um eine Flat-File SSG, das heißt, du brauchst keine zusätzliche Datenbank.

Wenn du noch nicht über Node.js 16.14+ verfügst, musst du zunächst Node.js installieren oder deine aktuelle Version aktualisieren. Danach kannst du mit der Installation von Docusaurus fortfahren.

Wir werden auch die Docusaurus-Beispielseite aus diesem GitHub-Repository verwenden. Du kannst sie oder eine cleane Installation von Docusaurus für dieses Tutorial verwenden.

Installationsprozess

Um die Installation von Docusaurus zu starten, musst du zunächst den folgenden Befehl ausführen:

npx create-docusaurus@latest  classic

Dadurch wird ein Ordner für dein Projekt erstellt und das klassische Theme darin eingebettet. Das klassische Theme enthält bereits einige vorkonfigurierte Funktionen wie einen Blog, benutzerdefinierte Seiten und ein CSS-Framework.

Nach der Installation musst du dann den folgenden Befehl ausführen, um den lokalen Server zu starten:

npm start

Wenn du eine optimierte, einsatzbereite Version erstellen willst, solltest du stattdessen diesen Befehl ausführen:

npm run build

Struktur

Sobald du deine Docusaurus-Instanz installiert hast, kannst du dein Projektverzeichnis öffnen und dir das „Skelett“ deiner neuen Website genauer ansehen.

Hier siehst du, wie die Dateistruktur aussieht:

my-website
├── blog
│ ├── 2019-05-28-hola.md
│ └── 2020-05-30-welcome.md
├── docs
│ ├── doc1.md
│ └── mdx.md
├── src
│ ├── css
│ │ └── custom.css
│ └── pages
│ ├── styles.module.css
│ └── index.js
├── static
│ └── img
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lock

Bei einigen dieser Dateien und Ordner gibt es ein paar Details zu beachten:

• /blog: Enthält alle Dateien, die mit deinem Blog zu tun haben.
• /docs: Enthält alle Dateien, die mit deinen Dokumenten zu tun haben. Du kannst ihre Reihenfolge in der Datei sidebar.js anpassen.
• /src: Enthält alle Dateien, die nicht zur Dokumentation gehören, wie Seiten oder benutzerdefinierte Komponenten.
• /src/pages: Alle JSX/TSX/MDX-Dateien werden in Seiten umgewandelt.
• /static: Statische Dateien, die in den endgültigen Build-Ordner kopiert werden.
• docusaurus.config.js: Docusaurus-Konfigurationsdatei.
• packaged.json: Jede Docusaurus-Site ist eine React-App, daher findest du hier alle Abhängigkeiten und Skripte, die sie für React verwendet.
• sidebar.js: Hier kannst du die Reihenfolge der Dokumente in der Seitenleiste festlegen.

Anpassen deiner Docusaurus-Installation

Wie du an der einfachen Dateistruktur sehen kannst, ist Docusaurus leicht zu bedienen und zu navigieren. Auch das Anpassen deiner Docusaurus-Website ist ein Kinderspiel. Du kannst diese Dateien mit deinem bevorzugten Texteditor oder einer IDE öffnen und bearbeiten.

Sehen wir uns einige der Anpassungsmöglichkeiten an, die dir sofort nach dem Auspacken zur Verfügung stehen.

Homepage

Als Erstes möchtest du wahrscheinlich die Standard-Homepage so anpassen, dass sie dein eigenes Projekt zeigt. Zum Glück ist es nicht kompliziert, die Docusaurus-Startseite nach Belieben zu verändern.

Um die Homepage zu ändern, öffnest du die Datei src/pages/index.js und nimmst die Änderungen direkt dort vor. Da es sich um eine typische React-Seite handelt, kannst du sie verändern oder neu aufbauen, indem du den Inhalt änderst oder eigene React-Komponenten erstellst.

Konfigurationsdatei

Als Nächstes werden wir in die wichtige Datei docusaurus.config.js eintauchen und einige wichtige Details für unsere Instanz ändern.

Name und Beschreibung

In der Konfigurationsdatei findest du Folgendes:

const config = {
title: 'My Site',
tagline: 'Dinosaurs are cool',
url: 'https://your-docusaurus-site.com',
baseUrl: '/',

Ändere diese Angaben einfach so, dass sie den Bedürfnissen deiner Website entsprechen, und speichere die Datei.

Navigationsleiste

Um deine Navigationsleiste zu bearbeiten, wähle den Punkt navbar.

In unserem Beispiel wollen wir einen Link zu Kinsta hinzufügen, das Element „Tutorial“ in „Starter-Dokumentation“ umbenennen und das Kinsta-Logo hinzufügen.

So würden wir vorgehen:

navbar: {
  title: 'Kinsta starters',
  logo: {  
    alt: 'Kinsta Logo',
    src: 'img/kinsta-logo-alpha-purple.png',
  },
  items: [
    {
      label: 'Kinsta starters',
      to: '/docs/intro',
    },
    {to: '/blog', label: 'Blog', position: 'left'},
    {
      href: 'https://github.com/kinsta',
      label: 'GitHub',
      position: 'right',
    },
  ],
},

Fußzeile

Die Fußzeilenanpassung in Docusaurus besteht aus zwei Bereichen: dem Fußzeileninhalt selbst und den Fußzeilenlinks.

Fußzeileninhalt

Der Hauptteil deines Fußzeileninhalts (mit Ausnahme der Linkliste) kann in deiner themeConfig.footer-Datei platziert werden. Dies ist der ideale Ort, um ein Logo und einen Copyright-Hinweis einzufügen.

Hier siehst du, wie wir unsere Fußzeilen-Konfiguration geändert haben:

module.exports = {
  themeConfig: {
    footer: {
      logo: {
        alt: 'Kinsta Logo',
        src: 'img/kinsta-logo.png',
        href: 'https://kinsta.com',
        width: 160,
        height: 51,
      },
      copyright: `Copyright © ${new Date().getFullYear()} Kinsta. Built with Docusaurus.`,
    },
  },
};

Links in der Fußzeile

Das Ändern der Links in der Fußzeile ist ähnlich wie das Ändern der oberen Navigationsleiste: Finde den Abschnitt footer in docusaurus.config.js und bearbeite ihn, bis er deinen Anforderungen entspricht.

So sieht unser Abschnitt footer aus:

footer: {
  style: 'dark',
  links: [
    {
      title: 'Docs',
      items: [
        {
          label: 'Kinsta starters',
          to: '/docs/intro',
        },
      ],
    },
    {
      title: 'Talk with us',
      items: [
        {
          label: 'Discord',
          href: 'https://discord.gg/vjRPMhFaBA',
        },
        {
          label: 'Support',
          href: 'https://kinsta.com/kinsta-support/',
        },
        {
          label: 'Twitter',
          href: 'https://twitter.com/kinsta',
        },
      ],
    },
    {
      title: 'More',
      items: [
        {
          label: 'Application Hosting',
          href: 'https://kinsta.com/application-hosting/',
        },
        {
          label: 'Database Hosting',
          href: 'https://kinsta.com/database-hosting/',
        },
        {
          label: 'WordPress Hosting',
          href: 'https://kinsta.com/wordpress-hosting/',
        },
        {
          label: 'DevKinsta',
          href: 'https://kinsta.com/devkinsta/',
        },
      ],
    },
  ],
};

Farben und CSS

Die klassische Voreinstellung für Docusaurus verwendet das Infima-CSS-Framework. Aus diesem Grund haben die Docusaurus-Macher ein sehr nützliches Webtool entwickelt, mit dem du die Farben und andere CSS-Elemente und -Deklarationen ändern kannst.

Nachdem du deine Einstellungen auf der Seite eingegeben hast, erstellt das Tool in Sekundenschnelle eine custom.css-Datei – komplett mit einer schönen Reihe von ergänzenden Farbtönen. Diese neue CSS-Datei kannst du dann als Referenz in das Verzeichnis /src/css deines Projekts kopieren.

Dokumentation

Die gesamte Dokumentation zu deiner neuen Website wird im Ordner /docs gespeichert. Natürlich kannst du den Ordnernamen in docusaurus.config.js ändern.

Erstelle einfach die Markdown-Dateien in deinem Text- oder HTML-Editor und lege sie in diesem Ordner ab. Jede Datei sollte wie folgt aussehen:

---
id: the-id
title: Title
---
# Rest of the document

Anhand der ID erstellt Docusaurus die URLs für die Artikel in diesem Unterordner: yourdomain.com/docs/{id}

Wir können auch Unterordner erstellen, um unsere Dokumentation in verschiedene, logische Abschnitte zu unterteilen. Damit diese Unterordner so funktionieren, wie wir es erwarten, müssen wir allerdings noch ein wenig mehr tun.

Nehmen wir an, wir erstellen einen neuen Dokumentenordner mit dem Namen „Starts“. Wenn wir dann die Homepage aktualisieren und auf den neuen Link „Starts“ klicken, der automatisch in der Seitenleiste eingefügt wurde, erhalten wir eine Fehlermeldung, weil es noch keine Indexseite in unserem neuen Ordner gibt.

Am einfachsten lässt sich dieses Problem beheben, indem du eine _category_.json-Datei erstellst, die den Index aller Seiten in diesem Ordner generiert. Du musst nur den folgenden Code hinzufügen:

{
  "label": "Starters",
  "position": 2,
  "link": {
    "type": "generated-index",
    "description": "All Kinsta Starters"
  },
};

Wie du siehst, wird die Seitenleiste entsprechend der Struktur deiner Dateien neu erstellt. Das liegt daran, dass die Datei sidebar.js diese tutorialSidebar enthält: [{type: 'autogenerated', dirName: '.'}],

Wenn du dich lieber selbst darum kümmerst, kannst du das einfach so ändern:

tutorialSidebar: [
  'intro',
  'hello',
  {
    type: 'category',
    label: 'Tutorial',
    items: ['tutorial-basics/create-a-document'],
  },
],

Blog

Docusaurus enthält ein raffiniertes Blog-Modul. Ein Blog neben deiner Hauptwebsite kann sehr nützlich sein, um deine Nutzer über Änderungen in deinem Projekt zu informieren oder um Projektnotizen als eine Art Changelog zu führen.

Jeder Beitrag besteht aus einem Frontmatter-Teil, etwa so:

---
slug: docusaurus-starter
title: Docusaurus Starter
authors: palmiak
tags: [starters, docusaurus]
---

…und natürlich aus dem Inhalt selbst. Außerdem gibt es einen sehr nützlichen Tag, mit dem du die Zusammenfassung des Beitrags in allen Beitragslisten einschränken kannst.

Es ist auch eine gute Idee, eine Datei authors.yml für die Credits zu erstellen. Die Datei sieht wie folgt aus:

palmiak:
name: Maciek Palmowski
title: DevRel
url: https://github.com/palmiak
image_url: https://github.com/palmiak.png

Dank dieser Datei hast du alle Daten der Autoren an einem Ort und kannst sie leicht nachschlagen.

Wie du deine Docusaurus-Website bei Kinsta bereitstellst

Neben WordPress-Websites, eigenständigen Anwendungen und Datenbanken kann Kinsta auch statische Websites hosten.

Das heißt, Kinsta eignet sich perfekt für deine Docusaurs-Websites – und für die Verwaltung all deiner Webprojekte – direkt von deinem MyKinsta-Dashboard aus.

Sobald deine Anwendung bereitgestellt wurde, kannst du die laufenden Analysen deiner Anwendung einsehen, sowohl live als auch in der Vergangenheit, mit Messungen wie:

• Bandbreitennutzung
• Erstellungszeit
• Ausführungszeit
• CPU-Nutzung
• Speicherverbrauch

Von Anfang bis Ende dauert der Bereitstellungsprozess über MyKinsta nur ein paar Minuten.

Los geht’s!

Voraussetzungen: Konfiguriere dein Docusaurus-Projekt

Um dein Docusaurus-Projekt auf der Application Hosting-Plattform von Kinsta zu hosten, musst du Folgendes tun:

1. Füge ein Namensfeld in deine package.json Datei ein. (Dies kann ein beliebiger Name sein und hat keinen Einfluss auf deine Bereitstellung.)
2. Füge ein Build-Skript in deine package.json-Datei ein. (Dein Docusaurus-Projekt sollte dies bereits enthalten.)
3. Installiere das npm-Paket serve und setze das Startskript auf serve build.

Wenn du diese Punkte abgehakt hast, kannst du mit dem eigentlichen Deployment deiner Website fortfahren.

Bereitstellen deines Docusaurus-Projekts

Befolge diese einfachen Schritte, um dich mit deinem GitHub-Konto zu verbinden und deine Docusaurus-Site zu starten:

1. Melde dich in deinem MyKinsta-Konto an und gehe im linken Menü auf die Registerkarte Anwendungen.
2. Klicke auf die blaue Schaltfläche Service hinzufügen und wähle Anwendung aus dem Dropdown-Menü.

   

3. Wenn du dich noch nicht über MyKinsta mit deinem GitHub-Konto verbunden hast, wird dir ein Modal angezeigt, das dich dazu auffordert. Klicke auf die Schaltfläche „Mit GitHub fortfahren„, um fortzufahren.

   

4. Es öffnet sich ein neues Fenster, in dem du gebeten wirst, Kinsta den Zugriff auf deine GitHub-Ressourcen und deren Verwaltung zu gestatten. Vergewissere dich, dass du mit dem richtigen GitHub-Konto angemeldet bist, und klicke dann auf die grüne Schaltfläche „Kinsta autorisieren“ am unteren Rand.

   

5. Du bist nun beim GitHub-Integrationsassistenten angelangt. Dies ist der letzte Schritt, bevor du deine Website einrichten kannst. Sieh dir die Felder genau an und fülle sie entsprechend deiner GitHub-Konfiguration und den Anforderungen deines Projekts aus. Wenn du eine Dockerdatei in deinem Repository hast, kannst du diese verwenden, um das Container-Image einzurichten; andernfalls wird Kinsta automatisch ein Container-Image für dich einrichten. Beachte, dass du eventuell deine GitHub-Berechtigungen bearbeiten musst, bevor du fortfahren kannst, vor allem, wenn dies deine erste Bereitstellung über Kinsta ist.

   

   Du kannst wählen, ob du Kinsta Zugriff auf alle Repositories oder nur auf bestimmte gewähren willst. Diese Berechtigungen können jederzeit in den Anwendungseinstellungen deines GitHub-Kontos angepasst werden.

   

6. Nachdem du deine Auswahl getroffen und bestätigt hast, werden dir die Details zu deiner Bereitstellung sowie die Optionen „Einstellungen ändern“ und „Neu bereitstellen“ angezeigt.

   

   Hier siehst du auch alle Fehler, die während der Bereitstellung aufgetreten sind, sowie Details zur Fehlerursache, damit du sie leicht beheben kannst. Wenn du Schwierigkeiten hast, das Problem zu beheben, findest du in der Dokumentation von Kinsta weitere Hinweise zu Rollout-Fehlern.

   

Wenn du bis hierher gekommen bist, ohne dass Fehler aufgetreten sind, dann herzlichen Glückwunsch – du hast deine Docusaurus-Website gerade erfolgreich über Kinsta bereitgestellt! Deine Anwendung (d. h. deine statische Website) ist verfügbar, sobald du den Assistenten abgeschlossen hast. Du kannst sie unter der URL deiner Anwendung aufrufen, die in der Regel lautet https://your-docusaurus-site.kinsta.app.

Hier ist ein erster Blick auf unsere Beispielsite auf Kinsta:

Zusammenfassung

Mit seinen überraschend leistungsstarken Funktionen, dem freundlichen Design, der intuitiven Navigation und dem Fokus auf den Inhalt ist es nicht schwer zu erkennen, warum Docusaurus ein hervorragendes Tool für alle Entwickler ist, die eine schlanke, gut organisierte statische Dokumentationsseite und/oder einen Blog erstellen und pflegen wollen.

Sobald du deine Seite mit Inhalten gefüllt hast, die deine Besucher/innen schätzen werden, wirst du feststellen, dass es noch weitere nützliche Funktionen gibt. Zum Beispiel sind die Suchmaschinenoptimierungsfunktionen von Docusaurus perfekt geeignet, um deine Sichtbarkeit bei einem größeren Publikum zu verbessern, während du an anderen Techniken arbeitest ,um in den SEO-Rankings voranzukommen.

Hast du schon etwas mit Docusaurus erstellt? Teile deine Projekte und Erfahrungen mit uns in den Kommentaren unten.

Maciek Palmowski

Maciek ist Webentwickler und arbeitet bei Kinsta als Development Advocate Analyst. Nach Feierabend verbringt er die meiste Zeit damit, zu programmieren, nach interessanten Neuigkeiten für seine Newsletter zu suchen oder Kaffee zu trinken.