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

Für leichtgewichtige Websites, Anwendungen und andere kleine Projekte wenden sich immer mehr Entwickler statischen Site-Generatoren über WordPress oder anderen Content-Management-Systemen (CMS) zu. Statische Websites bieten eine einfache und effektive Möglichkeit, Websites und Anwendungen zu erstellen, die schnell, sicher und leicht zu warten sind.

Docusaurus ist ein solcher statischer Site-Generator – und gewinnt in der Entwickler-Community schnell an Popularität. Müde von trägen Content-Management-Systemen? Triff Docusaurus! Ein statischer Website-Generator, der die Arbeit erledigt, ohne Sie zu verlangsamen. Lesen Sie weiter, um mehr zu erfahren Click to Tweet

In diesem Beitrag tauchen wir tief in die Vorteile der Verwendung von Docusaurs als Ihren statischen Website-Generator ein und warum es ein wachsender Favorit unter Entwicklern ist.

Was ist Docusaurus?

Docusaurus ist ein beliebter statischer Website-Generator, der React, eine der besten JavaScript-Bibliotheken, als UI-Bibliothek für die Seitenerstellung verwendet. Wie andere solche Generatoren ist es einfach einzurichten und zu ändern, und – was am wichtigsten ist – es bietet Ihnen alles, was Sie brauchen, um mit Ihrer statischen Website durchzustarten.

Was Docusaurus jedoch auszeichnet, ist, dass es Ihnen hilft, eine Website zu erstellen und zu verwalten, bei der der Inhalt eine Schlüsselrolle spielt . Sie können damit schnell und einfach eine vollständige Website erstellen – komplett mit einer Blog-Funktion – die Ihre Inhalte von Anfang an hervorhebt.

Da der Inhalt bei Docusaurus im Mittelpunkt steht, eignet es sich perfekt zum Erstellen von Dokumentationsseiten wie Wikis. Es nutzt auch Markdown, was sowohl für die Zusammenarbeit als auch für die Speicherung in einem Git-Repository ideal ist. Darüber hinaus verfügt es über eine Menge erstaunlicher Funktionen wie i18n, Suche und benutzerdefinierte Themen, auf die wir später noch näher eingehen werden.

Hier sind nur einige der herausragenden Merkmale, die Docusaurus zu einer soliden Option machen:

• Erstellt 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 Dokumentenübersetzung und Massen- oder Einzelbereitstellung

Wer verwendet Docusaurus?

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

Hier sind nur einige der größten Marken, die heute Docusaurus verwenden (und weitere werden bald folgen, da die Popularität von Docusaurus weiter zunimmt):

• Algolia DocSearch
• Scherz
• Nativ reagieren
• Superbasis

Und jeden Tag kommen mehr in ihre Reihen.

So installieren Sie Docusaurus

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

Und hier ist der coolste Teil: Wir werden weniger als eine Stunde brauchen, um alles hochzudrehen.

Tauchen wir ein!

Anforderungen

Docusarus benötigt Node.js 16.14 oder neuer. Es handelt sich um eine Flat-File-SSG, was bedeutet, dass Sie keine zusätzliche Datenbank benötigen.

Wenn Sie Node.js 16.14+ noch nicht verfügbar haben, müssen Sie zunächst Node.js installieren oder Ihre aktuelle Version aktualisieren. Dann können Sie mit dem Installationsprozess von Docusaurus weiter unten fortfahren.

Wir werden auch die Beispiel-Docusaurus-Site aus diesem GitHub-Repository verwenden. Sie können es oder eine saubere Installation von Docusaurus für dieses Tutorial verwenden.

Installationsprozess

Um den Docusaurus-Installationsprozess zu starten, müssen Sie zunächst den folgenden Befehl ausführen:

 npx [email protected] classic

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

Nach der Installation müssen Sie dann den folgenden Befehl ausführen, um den lokalen Server zu starten:

 npm start

Wenn Sie eine optimierte Version erstellen möchten, die bereit für die Bereitstellung ist, sollten Sie stattdessen Folgendes ausführen:

 npm run build

Struktur

Sobald Sie Ihre Docusaurus-Instanz installiert haben, können Sie Ihr Projektverzeichnis öffnen und sich das „Skelett“ Ihrer neuen Site genauer ansehen.

So sieht die Dateistruktur aus:

 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 sind einige Details zu beachten:

• /blog : Enthält alle Dateien, die sich auf Ihren Blog beziehen.
• /docs : Enthält alle Dateien, die sich auf Ihre Dokumente beziehen. Sie können ihre Reihenfolge in der Datei sidebar.js anpassen.
• /src : Enthält alle Nicht-Dokumentationsdateien 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 finden Sie hier alle Abhängigkeiten und Skripte, die sie für React verwendet.
• sidebar.js : Hier können Sie die Reihenfolge der Dokumente in der Seitenleiste festlegen.

Anpassen Ihrer Docusaurus-Installation

Wie Sie an der Einfachheit seiner Dateistruktur sehen können, ist Docusaurus einfach zu verwenden und zu navigieren. Ebenso ist das Anpassen Ihrer Docusaurus-Site ein Kinderspiel. Sie können diese Dateien mit Ihrem bevorzugten Texteditor oder Ihrer IDE öffnen und bearbeiten.

Lassen Sie uns einige der Anpassungsoptionen durchgehen, die Ihnen sofort zur Verfügung stehen.

Startseite

Das erste, was Sie wahrscheinlich jucken werden, ist, die Standard-Homepage anzupassen, um stattdessen Ihr eigenes Projekt auszustellen. Glücklicherweise ist es nicht kompliziert, die gewünschten Änderungen an der Docusaurus-Homepage vorzunehmen.

Um die Homepage zu ändern, öffnen Sie die Datei src/pages/index.js und nehmen Sie direkt dort Anpassungen vor. Es ist eine typische React-Seite, sodass Sie sie ändern oder neu erstellen können, indem Sie den Inhalt ändern oder benutzerdefinierte React-Komponenten erstellen.

Konfigurationsdatei

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

Name und Beschreibung

In der Konfigurationsdatei finden Sie:

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

Ändern Sie einfach diese Details entsprechend den Anforderungen Ihrer Website und speichern Sie die Datei.

Navigationsleiste

Um Ihre Navigationsleiste zu bearbeiten, suchen Sie das navbar .

Für unser Beispiel hier möchten 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', }, ], },

Fusszeile

Die Anpassung der Fußzeile in Docusaurus besteht aus zwei Abschnitten: dem Fußzeileninhalt selbst und den Fußzeilenlinks.

Inhalt der Fußzeile

Der Hauptteil Ihres Fußzeileninhalts (ohne die Linkliste) kann in Ihrer themeConfig.footer- Datei platziert werden. Dies ist der ideale Ort, um ein Logo und einen Copyright-Hinweis hinzuzufügen.

So haben wir unsere Fußzeilenkonfiguration geändert:

 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.`, }, }, };

Fußzeilen-Links

Das Ändern der Fußzeilen-Links ähnelt dem Ändern der oberen Navigationsleiste: Suchen Sie den footer in docusaurus.config.js und bearbeiten Sie ihn, bis er Ihren Anforderungen entspricht.

So haben wir unseren footer geändert:

 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

Das klassische Preset für Docusaurus verwendet das Infima CSS-Framework. Vor diesem Hintergrund haben die Docusaurus-Ersteller ein sehr nützliches Web-Tool entwickelt, mit dem Sie die Farben und andere CSS-Elemente und -Deklarationen ändern können.

Sobald Sie Ihre Einstellungen auf der Seite eingegeben haben, generiert das Tool in Sekundenschnelle eine custom.css- Datei – komplett mit einer schönen Suite ergänzender Töne. Sie können diese neue CSS-Datei dann als Referenz in das Verzeichnis /src/css Ihres Projekts kopieren.

Dokumentation

Die gesamte Dokumentation Ihrer neuen Website wird im Ordner /docs gespeichert. Natürlich können Sie den Ordnernamen in docusaurus.config.js ändern.

Erstellen Sie einfach die Markdown-Dateien in Ihrem Text- oder HTML-Editor und legen Sie sie in diesem Ordner ab. Jede Datei sollte so aussehen:

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

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

Wir können auch Unterordner erstellen, wenn Sie unsere Dokumentation in verschiedene, logische Abschnitte unterteilen möchten. Wir müssen jedoch ein wenig zusätzliche Arbeit leisten, damit diese Unterverzeichnisse so funktionieren, wie wir es erwarten würden.

Angenommen, wir erstellen einen neuen Dokumentenordner mit dem Namen „Starters“. Wenn wir dann die Startseite aktualisieren und auf den neuen Link „Starter“ klicken, der automatisch zu unserer Seitenleiste hinzugefügt wird, erhalten wir eine Fehlermeldung – weil sich in unserem neuen Ordner noch keine Indexseite befindet.

Der einfachste Weg, dies zu beheben, besteht darin, eine _category_.json- Datei zu erstellen, die den Index aller Seiten generiert, die in diesem Ordner gespeichert sind. Sie müssen nur den folgenden Code hinzufügen:

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

Wie Sie sehen können, wird die Seitenleiste neu generiert, um der Struktur Ihrer Dateien zu entsprechen. Das liegt daran, dass die Datei sidebar.js dieses tutorialSidebar enthält: [{type: 'autogenerated', dirName: '.'}],

Wenn Sie sich lieber selbst darum kümmern möchten, können Sie dies einfach so ändern:

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

Bloggen

Docusaurus enthält ein schickes Blog-Modul. Ein Blog neben Ihrer Hauptwebsite kann sehr nützlich sein, um Ihre Benutzerbasis über Änderungen in Ihrem Projekt zu informieren oder um Projektnotizen als eine Art Änderungsprotokoll zu führen.

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

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

…und natürlich der Inhalt selbst. Es hat auch ein sehr nützliches <!--truncate--> Tag, das dabei hilft, die in allen Post-Listen angezeigte Post-Zusammenfassung einzuschränken.

Es ist auch eine großartige Idee, eine authors.yml- Datei für Credits zu erstellen. Die Datei sieht so aus:

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

Dank dieser Datei haben Sie alle Daten des Autors zum einfachen Nachschlagen an einem Ort.

So stellen Sie Ihre Docusaurus-Website bei Kinsta bereit

Zusätzlich zu WordPress-Sites, eigenständigen Anwendungen und Datenbanken kann Kinsta statische Websites hosten.

Das bedeutet, dass es perfekt für deine Docusaurs-Sites ist – und für die Verwaltung all deiner Webprojekte – direkt von deinem MyKinsta-Dashboard aus.

Sobald Ihre Anwendung bereitgestellt wurde, können Sie die laufenden Analysen Ihrer Anwendung überprüfen, sowohl live als auch historisch, mit Messungen, darunter:

• Bandbreitennutzung
• Bauzeit
• Laufzeit
• CPU auslastung
• Speichernutzung

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

Lass uns anfangen!

Voraussetzungen: Konfiguration Ihres Docusaurus-Projekts

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

1. Fügen Sie ein Namensfeld in Ihre Datei „package.json“ ein. (Dies kann alles sein und wirkt sich nicht auf Ihre Bereitstellung aus.)
2. Fügen Sie ein Build-Skript in Ihre Datei „package.json“ ein. (Ihr Docusaurus-Projekt sollte dies bereits enthalten.)
3. Installieren Sie das npm-Paket „serve“ und stellen Sie das Startskript auf „serve build“ ein.

Sobald diese abgehakt sind, können Sie mit der tatsächlichen Bereitstellung Ihrer Website fortfahren.

Bereitstellen Ihres Docusaurus-Projekts

Befolgen Sie diese einfachen Schritte, um sich mit Ihrem GitHub-Konto zu verbinden und Ihre Docusaurus-Site zu starten:

1. Melde dich bei deinem MyKinsta-Konto an und navigiere im Menü auf der linken Seite zur Registerkarte Anwendungen .
2. Klicken Sie auf die blaue Schaltfläche Dienst hinzufügen und wählen Sie Anwendung aus der Dropdown-Liste.

   

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

   

4. Es öffnet sich ein neues Fenster, in dem Sie um Ihre Erlaubnis gebeten werden, Kinsta zu autorisieren, auf Ihre GitHub-Ressourcen zuzugreifen und diese zu verwalten. Vergewissere dich, dass du beim richtigen GitHub-Konto angemeldet bist, und klicke dann unten auf die grüne Schaltfläche Kinsta autorisieren .

   

5. Sie befinden sich jetzt im GitHub-Integrationsassistenten. Dies ist der letzte Schritt, bevor Sie Ihre Site bereitstellen können. Prüfen Sie sorgfältig die angezeigten Felder und füllen Sie sie gemäß Ihrer GitHub-Konfiguration und den Anforderungen Ihres Projekts aus. Wenn Sie ein Dockerfile in Ihrem Repository haben, können Sie dieses verwenden, um das Container-Image einzurichten; Andernfalls richtet Kinsta automatisch ein Container-Image für dich ein. Beachte, dass du möglicherweise deine GitHub-Berechtigungen bearbeiten musst, bevor du fortfahren kannst, insbesondere wenn dies deine erste Bereitstellung über Kinsta ist.

   

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

   

6. Nachdem Sie Ihre Auswahl getroffen und Ihre Auswahl bestätigt haben, werden Ihnen Ihre Bereitstellungsdetails sowie Optionen zum Ändern der Einstellungen oder zum erneuten Bereitstellen angezeigt.

   

   Hier sehen Sie auch alle Fehler, die während der Bereitstellung aufgetreten sind, zusammen mit Details zur Ursache des Fehlers, damit Sie ihn einfach beheben können. Wenn Sie Schwierigkeiten haben, das Problem zu beheben, finden Sie zusätzliche Anleitungen zu Rollout-Fehlern in der Dokumentation von Kinsta.

   

Wenn Sie bis hierher ohne Fehler gekommen sind, dann herzlichen Glückwunsch – Sie haben gerade Ihre Docusaurus-Site erfolgreich über Kinsta bereitgestellt! Ihre Anwendung (dh Ihre statische Site) ist verfügbar, sobald Sie den Assistenten abgeschlossen haben. Sie können es unter der URL Ihrer Anwendung anzeigen, die üblicherweise https:// your-docusaurus-site .kinsta.app lautet.

Hier ist unser erster Blick auf unsere Beispielseite auf Kinsta:

Zusammenfassung

Mit seinen überraschend leistungsstarken Funktionen, dem benutzerfreundlichen Design, der intuitiven Navigation und dem Fokus auf Inhalte ist es nicht schwer zu verstehen, warum Docusaurus als hervorragendes Tool für jeden Entwickler gilt, der eine optimierte, gut organisierte statische Dokumentationsseite und/oder einfach bereitstellen und pflegen möchte bloggen. Schalten Sie Ihr Webentwicklungsspiel um! Verabschieden Sie sich von klobigen CMS und begrüßen Sie Docusaurus – einen einfachen statischen Website-Generator, der das Entwicklerspiel verändert. Sieh es dir gleich hier an ️ Click to Tweet

Sobald Sie Ihre Website mit Inhalten gefüllt haben, die Ihre Besucher schätzen werden, werden Sie beginnen, zusätzliche integrierte Funktionen zur Kenntnis zu nehmen, die sich als nützlich erweisen. Beispielsweise sind die Suchmaschinenoptimierungsfunktionen von Docusaurus perfekt, um Ihnen zu helfen, eine verbesserte Sichtbarkeit durch ein breiteres Publikum zu erreichen, während Sie an anderen Techniken arbeiten, um in SEO-Rankings voranzukommen.

Haben Sie etwas mit Docusaurus gebaut? Teilen Sie uns Ihre Projekte und Erfahrungen im Kommentarbereich unten mit.