In der schnelllebigen digitalen Welt von heute ist eine gut organisierte und optisch ansprechende Dokumentation oder Blog-Site unerlässlich, um die Aufmerksamkeit deines Publikums zu wecken und es bei der Stange zu halten. Aber wie kannst du das erreichen, ohne endlose Stunden in die Webentwicklung zu investieren?
In diesem Artikel wird erklärt, wie du mit VuePress, einem minimalistischen, aber leistungsstarken Static Site Generator (SSG), eine schnelle Dokumentations- und Blogseite erstellen und anpassen kannst.
Was ist VuePress?
VuePress ist ein Open-Source-Framework, das sich auf die Erstellung statischer Websites spezialisiert hat und vor allem für Dokumentationen und Blogs geeignet ist. Es wurde von Evan You, dem Genie hinter Vue.js, entwickelt und verkörpert die Philosophie der Einfachheit und Benutzerfreundlichkeit, für die Vue.js bekannt ist.
Warum VuePress verwenden?
Hier sind einige überzeugende Gründe, warum VuePress die perfekte Wahl für dich sein könnte.
- Einfachheit von Markdown: VuePress vereinfacht die Inhaltserstellung mit Markdown und macht es einfach, Inhalte ohne komplexe Formatierung zu schreiben und zu strukturieren.
- Vue.js-Integration: VuePress integriert nahtlos Vue.js und ermöglicht so interaktive und dynamische Webelemente für ein ansprechendes Nutzererlebnis.
- Leistung und Anpassbarkeit: VuePress bietet eine exzellente Performance mit schnell ladenden statischen Websites und umfangreiche Anpassungsmöglichkeiten, um deinen Stil und deine Bedürfnisse zu erfüllen.
Erste Schritte mit VuePress
Bevor du dich mit VuePress beschäftigst, solltest du sicherstellen, dass du Node.js oder Yarn Classic auf deinem Computer installiert hast. Es gibt zwei Möglichkeiten, mit VuePress zu beginnen: Entweder du verwendest den create-vuepress-site-Generator, der dir dabei hilft, die grundlegende VuePress-Seitenstruktur zu erstellen, oder du verwendest die manuelle Installation.
In diesem Artikel wollen wir die manuelle Installation verwenden.
- Erstelle ein neues Verzeichnis und ändere es:
mkdir vuepress-starter && cd vuepress-starter- Initialisiere mit deinem bevorzugten Paketmanager. Für diesen Artikel verwenden wir Yarn:
yarn init- Installiere VuePress in deinem Projekt als Entwickler-Abhängigkeit:
yarn add -D vuepress- Erstelle einen docs-Ordner, in dem du deinen gesamten Code ablegen kannst, und erstelle dann eine README.md-Datei, die als Indexdatei deines Projekts dient, ähnlich wie index.html:
mkdir docs && echo '# Hello VuePress' > docs/README.md- Öffne dein Projekt in einem Code-Editor und füge die folgenden Skripte zu deiner package.json-Datei hinzu, damit du deine Seite bereitstellen und bauen kannst:
"scripts": {
"dev": "vuepress dev docs",
"build": "vuepress build docs"
},Du kannst deine Seite jetzt mit dem Befehl yarn dev bereitstellen. VuePress wird deinen Entwicklungsserver unter http://localhost:8080 starten.
Du hast nun eine Dokumentationsseite erstellt. Du wirst feststellen, dass VuePress von Haus aus ein sauberes, minimalistisches Standard-Theme bietet. Es ist jedoch in hohem Maße anpassbar und gibt dir die kreative Freiheit, ein einzigartiges Aussehen für deine Website zu gestalten.
Dokumentationsseiten erstellen
VuePress folgt einer einfachen Verzeichnisstruktur, um die Dokumentation zu organisieren. In deinem Projektordner findest du das von uns erstellte docs-Verzeichnis, in dem du Markdown-Dateien (.md) für deine Dokumentationsseiten erstellen kannst.
Du kannst zum Beispiel Dateien wie getting-started.md, usage.md und troubleshooting.md erstellen. Diese Dateien werden automatisch zu Routen, auf die du zugreifen kannst, wenn du zu http://localhost:8080/getting-started, http://localhost:8080/usage und http://localhost:8080/troubleshooting navigierst.
Um die Organisation deiner Dokumentation zu verbessern, kannst du spezielle Ordner für verwandte Dokumentationsseiten erstellen. Du kannst zum Beispiel einen Ordner mit dem Namen guide erstellen und ihn mit speziellen Anleitungen wie using-kinsta-stsh.md organisieren. Wenn du diese Struktur verwendest, wird der Inhalt von using-kinsta-stsh.md über eine URL wie http://localhost:8080/guide/using-kinsta-stsh zugänglich.
Du kannst auch eine README.md- oder index.md-Datei im Stammverzeichnis des Leitfadens erstellen. Diese Datei dient als Indexseite, die es den Nutzern ermöglicht, zu http://localhost:8080/guide/ zu navigieren und über eine Seitenleiste, die du im nächsten Abschnitt konfigurieren kannst, bequem auf die Inhalte zuzugreifen.
In diesem VuePress-Beispiel-Repository kannst du sehen, dass alle diese Dateien erstellt wurden und dass jeder Datei einige Markdown-Inhalte hinzugefügt wurden. Du kannst deine eigenen Dateien nach deinen Wünschen erstellen, entweder von Grund auf, um sie an deine Bedürfnisse anzupassen, oder indem du dich von den im Repository verfügbaren Inhalten inspirieren lässt.
Anpassen des VuePress-Erscheinungsbildes
Wenn du deine Dokumentationsseite mit Inhalten gefüllt hast, kann es schwierig werden, sich darin zurechtzufinden, vor allem, wenn du viele Dateien zu verwalten hast. Mit VuePress kannst du jedoch die Navigationsstruktur deiner Seite anpassen, um sie benutzerfreundlicher und übersichtlicher zu gestalten.
Um das Aussehen und die Navigation deiner Seite anzupassen, erstelle einen Ordner .vuepress im Hauptverzeichnis deines Projekts. Dieser Ordner enthält Konfigurationsdateien und Assets für deine VuePress-Site.
Konfiguration der Navigation
Erstelle im Ordner .vuepress eine config.js-Datei. Du kannst auch andere Dateiformate wie YAML (.yml), TOML (.toml) oder TypeScript (.ts) für deine Konfiguration verwenden.
In deiner config.js Datei kannst du die Navigationsstruktur deiner Seite mit dem themeConfig Objekt definieren. Hier ist eine Beispielkonfiguration:
module.exports = {
title: 'Kinsta Vuepress',
description: 'A VuePress QuickStart for Kinsta',
themeConfig: {
nav: [
{
text: 'Guide',
link: '/guide/',
},
{
text: 'Static Site Hosting',
link: 'https://kinsta.com/static-site-hosting/',
},
],
sidebar: {
'/guide/': [
{
title: 'Guide',
collapsable: false,
children: ['', 'using-kinsta-stsh'],
},
],
},
},
};In diesem Beispiel konfigurieren wir die Seiten title und description, definieren Navigationslinks und richten eine Seitenleiste für den Bereich /guide/ ein.
Das Array nav legt die Navigationslinks im oberen Bereich deiner Website fest. Das Sidebar-Objekt definiert die Struktur der Seitenleiste für bestimmte Abschnitte. In diesem Fall ist es für den Bereich /guide/ konfiguriert.
Du kannst mehr über die Konfiguration der Navigationsleiste in der VuePress-Dokumentation lesen.
Styling
Mit VuePress kannst du das Aussehen deiner Seite durch Stile anpassen. Du kannst entweder die Standardstile mit Hilfe einiger definierter Variablen überschreiben oder deinen eigenen Stil definieren. Um beides zu tun, erstelle einen Styles-Ordner im .vuepress-Ordner
Um das Styling der Standardvorgabe einfach zu überschreiben oder einige Variablen für die spätere Verwendung zu definieren, kannst du eine palette.styl-Datei in .vuepress/styles erstellen. Hier findest du einige vordefinierte Variablen, die du anpassen kannst:
// colors
$accentColor = #5333ED
$textColor = #2c3e50
$borderColor = #eaecef
$codeBgColor = #282c34
$arrowBgColor = #ccc
$badgeTipColor = #42b983
$badgeWarningColor = darken(#ffe564, 35%)
$badgeErrorColor = #DA5961
// layout
$navbarHeight = 3.6rem
$sidebarWidth = 20rem
$contentWidth = 740px
$homePageWidth = 960px
// responsive breakpoints
$MQNarrow = 959px
$MQMobile = 719px
$MQMobileNarrow = 419pxDiese Variablen können verwendet werden, um ein einheitliches Styling auf deiner Website zu gewährleisten. VuePress bietet auch eine praktische Möglichkeit, zusätzliche Stile hinzuzufügen. Du kannst eine index.styl-Datei im Ordner .vuepress/styles erstellen, in der du die normale CSS-Syntax verwenden kannst:
.content {
font-size 30px
}Mehr über das Styling von VuePress erfährst du in der offiziellen Dokumentation.
Komponenten verwenden
VuePress unterstützt die Verwendung von Komponenten, um die Funktionalität und das Aussehen deiner Seiten zu verbessern. Du kannst Vue-Komponenten erstellen und sie in deine Markdown-Dateien einfügen.
Erstelle einen components-Ordner in .vuepres, und alle *.vue Dateien, die du in .vuepress/components findest, werden automatisch als globale Komponenten registriert.
Du kannst zum Beispiel zwei Komponenten erstellen: HomeOptions.vue und HostingBanner.vue:
.
└─ .vuepress
└─ components
├─ HomeOptions.vue
└─ HostingBanner.vueInnerhalb dieser vue.js-Komponentendateien kannst du CSS-Codes hinzufügen. Fügen wir nun Code zu den Komponenten HomeOptions.vue und HostingBanner.vue hinzu.
Füge den folgenden Code zu HomeOptions.vue hinzu:
<template>
<div class="options">
<div class="option">
<a
href="https://kinsta.com/docs/static-site-hosting/static-site-quick-start-examples/"
target="_blank"
>
<h3>Quick Start Examples</h3>
</a>
<p>Explore quick start examples for setting up static sites.</p>
</div>
<div class="option">
<a
href="https://kinsta.com/docs/static-site-hosting/getting-started-static-site-hosting/"
target="_blank"
>
<h3>Getting Started</h3>
</a>
<p>Learn how to get started with static site hosting.</p>
</div>
<div class="option">
<a
href="https://kinsta.com/docs/static-site-hosting/manage-static-sites/"
target="_blank"
>
<h3>Manage Static Sites</h3>
</a>
<p>Discover how to efficiently manage your static sites.</p>
</div>
</div>
</template>
<style scoped>
a {
color: #2c3e50;
}
a:hover {
color: #5333ed;
}
.options {
display: flex;
gap: 10px;
margin: 40px 0;
}
.option {
border: 2px solid #eaecef;
border-radius: 5px;
padding: 10px;
}
</style>Füge auch den folgenden Code in HostingBanner.vue ein:
<template>
<div class="banner">
<p>Host Your Static Site With Kinsta for Free!</p>
<a
href="https://kinsta.com/docs/static-site-hosting/"
target="_blank"
class="btn"
>Read More</a
>
</div>
</template>
<style> scoped>
.banner {
background: rgb(156, 85, 34);
background: linear-gradient(
90deg,
rgba(156, 85, 34, 1) 0%,
rgba(32, 50, 103, 1) 42%,
rgba(13, 18, 25, 1) 69%,
rgba(22, 47, 60, 1) 100%
);
color: #fff;
padding: 20px;
border-radius: 5px;
display: flex;
justify-content: center;
align-items: center;
flex-direction: column;
}
.banner p {
width: 600px;
font-size: 40px;
font-weight: bold;
text-align: center;
line-height: 50px;
}
.banner .btn {
border-radius: 5px;
padding: 15px;
color: #1f1f1f;
font-weight: bold;
background: #fff;
display: inline-block;
margin-bottom: 10px;
}
.banner .btn:hover {
background: #111319;
color: #fff;
}
</style>Innerhalb einer beliebigen Markdown-Datei kannst du die Komponenten dann direkt verwenden (die Namen werden aus den Dateinamen abgeleitet):
<HomeOptions/>
<HostingBanner/>Lies mehr über Komponenten in VuePress in der Dokumentation.
Startseite anpassen
In VuePress bietet das Standard-Theme ein vorgefertigtes Startseiten-Layout, das du nutzen kannst, um einen ansprechenden und informativen Startpunkt für deine Seite zu schaffen. Um dieses Startseiten-Layout zu nutzen, musst du home: true angeben und einige zusätzliche Metadaten in das YAML Frontmatter deiner Root README.md-Datei einfügen.
Hier ist ein Beispiel für den YAML-Frontmatter:
---
home: true
heroImage: /hero.png
heroText: Hero Title
tagline: Hero subtitle
actionText: Get Started →
actionLink: /guide/
features:
- title: Simplicity First
details: Minimal setup with markdown-centered project structure helps you focus on writing.
- title: Vue-Powered
details: Enjoy the dev experience of Vue + webpack, use Vue components in markdown, and develop custom themes with Vue.
- title: Performant
details: VuePress generates pre-rendered static HTML for each page, and runs as an SPA once a page is loaded.
footer: MIT Licensed | Copyright © 2018-present Evan You
---Mit all diesen Konfigurationen sieht deine Dokumentations-Startseite wie folgt aus:
Du kannst heroText und tagline oder jeden anderen Wert deaktivieren, indem du die entsprechenden Felder auf null setzt, wenn du ein einfacheres Layout bevorzugst oder es nicht einbauen möchtest. Alle Inhalte, die du nach dem YAML-Frontmatter (d.h. dem Metadaten-Abschnitt) einfügst, werden wie normales Markdown behandelt und nach dem Features-Abschnitt gerendert.
Wenn du ein komplett individuelles Startseiten-Layout möchtest, unterstützt VuePress auch Custom Layouts. Außerdem kannst du mit der Markdown-Slot-Syntax einen Rich-Text-Footer erstellen, der mehr Flexibilität bei der Darstellung von Footer-Inhalten bietet. Hier ist ein Beispiel dafür, wie du eine Rich-Text-Fußzeile einrichtest:
---
home: true
---
::: slot footer
Made with ❤️ by Kinsta. [Static Site Hosting](https://kinsta.com/static-site-hosting/)
:::In diesem Fall ermöglicht dir der Inhalt im Abschnitt ::: slot footer das Einfügen von Links und zusätzlichen Informationen in den Fußzeilenbereich deiner Startseite.
Nachdem du nun weißt, wie du die oben genannten Anpassungen vornehmen kannst, füge die zuvor erstellten Komponenten zur Startseite hinzu und entferne einige Optionen, damit die Startseite besser aussieht:
---
home: true
tagline: A VuePress QuickStart for Kinsta
actionText: Quick Start →
actionLink: /guide/
---
<HomeOptions/>
<HostingBanner/>
::: slot footer
Made with ❤️ by Kinsta. [Static Site Hosting](https://kinsta.com/static-site-hosting/)
:::
Wenn du diese VuePress-Anpassungstechniken befolgst, kannst du eine Dokumentationsseite erstellen, die nicht nur wertvolle Inhalte bietet, sondern auch ein hervorragendes Nutzererlebnis mit einer organisierten Navigation und einem ansprechenden Design.
Mehr über die Anpassung des Standard-Themes erfährst du in der Dokumentation.
Einen Blog-Bereich mit VuePress einrichten
Das Hinzufügen eines Blog-Bereichs zu deiner VuePress-Website ist ein Kinderspiel, denn VuePress ermöglicht es dir, eigene Vue-Komponenten zu schreiben, die in jede Markdown-Datei eingefügt werden können. Lass uns eine Komponente erstellen, die die Liste der Blogbeiträge anzeigt.
Erstelle eine Datei BlogIndex.vue im Ordner components und füge den folgenden Code hinzu:
<template>
<div>
<div v-for="post in posts" v-bind:key="post.path">
<h2>
<router-link> :to="post.path">{{ post.frontmatter.title }}</router-link>
</h2>
<p>{{ post.frontmatter.description }}</p>
<p><router-link> :to="post.path">Read more</router-link></p>
</div>
</div>
</template>
<script>>
export default {
computed: {
posts() {
return this.$site.pages
.filter(
(x) => x.path.startsWith('/blog/') && !x.frontmatter.blog_index
)
.sort(
(a, b) =>
new Date(b.frontmatter.date) - new Date(a.frontmatter.date)
);
},
},
};
</script>In dem mitgelieferten Codeschnipsel definierst du ein Vue-Template, das deine Blogbeiträge mit v-for in einer Schleife durchläuft und für jeden Beitrag den Titel, die Beschreibung und einen „Weiterlesen“-Link anzeigt.
Der Skriptabschnitt exportiert eine Vue-Komponente, die die Blogbeiträge berechnet und abruft. Diese Beiträge werden nach ihrem Pfad (beginnend mit /blog/) und dem Fehlen des Attributs blog_index frontmatter gefiltert. Anschließend werden sie nach Datum absteigend sortiert, um die neuesten Beiträge zuerst anzuzeigen.
Wenn du neue Blogeinträge erstellst, musst du das Beitragsdatum als Teil der Frontmatter-Informationen angeben. Dadurch werden die Beiträge so sortiert, dass die neuesten Beiträge zuerst erscheinen.
Um die Blogeinträge zu speichern, erstelle einen Ordner namens blog im Stammverzeichnis des Projekts. In diesem Ordner fügst du eine README.md-Datei hinzu. Dies wird der Blog-Index sein, in den du die Komponente BlogIndex einfügst, um alle Blogbeiträge aufzulisten.
---
blog_index: true
---
# Blog
Welcome To Our Blog
<BlogIndex />Achte darauf, dass du das Attribut blog_index frontmatter hinzufügst, da es dafür sorgt, dass der Blog-Index selbst nicht unter den einzelnen Blog-Beiträgen aufgeführt wird. Dieses Attribut wird beim Filtern der Beiträge in der Eigenschaft posts computed der Komponente BlogIndex.vue verwendet.
Als Nächstes erstellst du einen Blog-Ordner im Stammverzeichnis deines Projekts, in dem alle Blog-Beiträge gespeichert werden und in dem du jeden Beitrag erstellst. Erstelle zum Beispiel eine Datei first-post.md und füge den folgenden Markdown-Inhalt hinzu:
---
title: "My Exciting VuePress Blog Journey"
date: 2023-09-28
description: "Exploring VuePress, a versatile static site generator, and sharing my experiences along the way."
---
# My Exciting VuePress Blog Journey
In this inaugural blog post, I embark on an exciting journey with VuePress, a powerful static site generator that's perfect for creating documentation, blogs, and more. As I delve into the world of VuePress, I'll be sharing my experiences, insights, and tips on making the most out of this fantastic tool.Stelle sicher, dass du für jeden Blog-Beitrag wichtige Einstellungen wie den Titel des Beitrags, das Datum und andere relevante Metadaten definierst. Diese sorgfältige Organisation stellt sicher, dass deine Blogposts zusammenhängend dargestellt werden und ein ansprechendes Leseerlebnis für dein Publikum bieten.
Schließlich kannst du die Blog-Navigation in der Datei .vuepress/config.js zu deiner Navigationsleiste hinzufügen:
nav: [
{
text: 'Guide',
link: '/guide/',
},
{ text: 'Blog', link: '/blog/' },
{
text: 'Static Site Hosting',
link: 'https://kinsta.com/static-site-hosting/',
},
],Es gibt noch viel mehr, was du mit VuePress machen kannst, z. B. Plugins hinzufügen, ein eigenes Theme verwenden oder sogar ein eigenes Theme erstellen.
VuePress Static Site auf Kinsta bereitstellen
Kinsta ermöglicht es dir, bis zu 100 statische Websites kostenlos zu hosten. Dazu musst du deinen Code zu deinem bevorzugten Git-Anbieter (Bitbucket, GitHub oder GitLab) pushen und ihn dann auf Kinsta bereitstellen.
Bevor du deine Dateien an einen Git-Anbieter weitergibst, solltest du im Stammverzeichnis deines Projekts eine .gitignore-Datei erstellen, in der du die Dateien und Ordner angibst, die Git beim Weitergeben deines Codes ignorieren soll:
# dependencies
/node_modules
# build directory
./docs/.vuepress/dist
/publicFür diesen Leitfaden verwenden wir GitHub. Erstelle ein Repository auf GitHub, um deinen Quellcode zu veröffentlichen. Sobald dein Repository fertig ist, befolge die folgenden Schritte, um deine statische Website auf Kinsta bereitzustellen:
- Logge dich ein oder erstelle ein Konto, um dein MyKinsta-Dashboard zu sehen.
- Autorisiere Kinsta mit deinem Git-Anbieter.
- Klicke in der linken Seitenleiste auf Statische Sites und dann auf Website hinzufügen.
- Wähle das Repository und den Zweig aus, von dem aus du deployen möchtest.
- Gib deiner Site einen eindeutigen Namen.
- Füge die Build-Einstellungen in folgendem Format hinzu:
- Build-Befehl:
npm run build - Node-Version:
16.20.0 - Veröffentlichungsverzeichnis:
./docs/.vuepress/distoderpublic
- Build-Befehl:
- Zum Schluss klickst du auf Website erstellen.
Und das war’s! Innerhalb weniger Sekunden hast du eine fertige Website. Du erhältst einen Link, über den du auf die bereitgestellte Version deiner Website zugreifen kannst. Du kannst später deine eigene Domain und dein SSL-Zertifikat hinzufügen, wenn du möchtest.
Als Alternative zum Static Site Hosting kannst du dich auch für das Anwendungs-Hosting von Kinsta entscheiden, das mehr Flexibilität beim Hosting, eine größere Bandbreite an Vorteilen und den Zugang zu robusteren Funktionen bietet. Dazu gehören z. B. Skalierbarkeit, benutzerdefinierte Bereitstellung mit einem Dockerfile und umfassende Analysen mit Echtzeit- und historischen Daten.
Zusammenfassung
VuePress ist ein vielseitiges und leistungsstarkes Tool für die Erstellung von schnellen Dokumentations- und Blog-Seiten. Mit seiner einfachen Einrichtung, den anpassbaren Themes und Plugins kannst du eine informative und optisch ansprechende Plattform für dein Publikum aufbauen.
Beginne noch heute mit der Erstellung deiner VuePress-Seite und teile dein Wissen mit der Welt, indem du sie kostenlos auf unserem Static Site Hosting hostest!
Hast du schon etwas mit VuePress erstellt? Teile uns deine Projekte und Erfahrungen gerne in den Kommentaren mit.
Joel ist Frontend-Entwickler und arbeitet bei Kinsta als Technical Editor. Er ist ein leidenschaftlicher Lehrer mit einer Vorliebe für Open Source und hat über 200 technische Artikel geschrieben, die sich hauptsächlich um JavaScript und seine Frameworks drehen.
Schreibe einen Kommentar