Erstellen Sie eine statische Website mit VitePress für schöne Hilfe Dokumentation

Einführung

Ich war schon immer ein Fan von statischen Website-Generatoren, mit denen man eine HTML-Website auf der Grundlage von Text (in der Regel in Markdown) mit Unterstützung von Community-Themen erstellen kann. Auf diese Weise kann man mehr Zeit mit dem Schreiben von Inhalten verbringen als mit der Verwaltung der Infrastruktur für ein Content-Management-System (CMS) wie WordPress, das eine Datenbank und eine Benutzeroberfläche für die Eingabe von Inhalten erfordert. Wenn ich meine drei Gründe zusammenfassen könnte, warum ich statische Website-Generatoren mag, wären das folgende:

• Leistung (Seiten werden vorgerendert)

• Die Möglichkeit, Themen zu haben

• Sie erfordern keinen Code auf der Serverseite

Lassen Sie uns in einem beliebten genannt springen, VitePress.

vitepressmain.png

Eine Fibel über VitePress

VitePress ist VuePress' kleiner Bruder von VuePress, und es wird von Vite und Vue.js. Für diejenigen, die es nicht wissen, Vite ist ein Build-Tool, das eine schnellere und schlankere Entwicklung Erfahrung für moderne Web-Projekte bieten soll, so könnte es Sinn machen, es mit einem statischen Website-Generator wie VitePress Paar. Vue.js ist ein progressives JavaScript-Framework für die Erstellung von Web-Benutzeroberflächen. Eines der ursprünglichen Probleme mit VuePress war, dass es sich um eine Webpack-Anwendung handelte und es viel Zeit in Anspruch nahm, einen Entwicklungsserver für ein einfaches Dokument aufzusetzen. VitePress löst diese Probleme mit einem fast sofortigen Server-Start, einer On-Demand-Kompilierung, die nur die Seite kompiliert, die bedient wird, und blitzschnelle HMR. Lassen Sie uns beginnen!

Von Null auf eine funktionierende statische Website

Erstellen Sie zunächst einen Ordner, in dem Sie Ihre statische Website entwickeln werden.

Dann initialisieren Sie es mit Garn oder NPM. Für dieses Beispiel werden wir Yarn verwenden. Wenn Sie Yarn noch nicht installiert haben, können Sie es auf der Download-Seite. Für diejenigen, die NPM verwenden, findet sich die VitePress-Dokumentation hier.

Es werden Ihnen eine Reihe von Fragen gestellt, die Sie entweder ausfüllen oder, wie ich es getan habe, leer lassen können.

yarn init
yarn init v1.22.19
question name (static-starter):
question version (1.0.0):
question description:
question entry point (index.js):
question repository url:
question author:
question license (MIT):
question private:
success Saved package.json
Done in 26.93s.

Hinweis: Sie können diese Angaben auch später bei der Konfiguration der Website machen.

Zu diesem Zeitpunkt haben Sie nur eine einzige package.json Datei. Sie sollten nun VitePress und Vue als Dev-Abhängigkeiten für das Projekt hinzufügen.

yarn add --dev vitepress vue

Jetzt brauchen wir einen Speicherort für die Dokumente, die wir erstellen werden, und fügen ein Beispieldokument hinzu.

mkdir docs 
cd docs
touch index.md

Bearbeiten Sie den Inhalt von index.md um den folgenden Text einzufügen:

# Hello VitePress.

Sie sollten nun folgende Dateien und Ordner haben:

docs 
├── index.md
node_modules 
package.json 
yarn.lock

Wir müssen den folgenden scripts Abschnitt zu unserem package.json.

{
  "name": "static-starter",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT",
  "devDependencies": {
    "vitepress": "^1.0.0-alpha.21",
    "vue": "^3.2.41"
  },
    "scripts": {
      "docs:dev": "vitepress dev docs",
      "docs:build": "vitepress build docs",
      "docs:serve": "vitepress serve docs"
  }
}

So können wir je nach Situation verschiedene Profile erstellen.

Sie können den Server bereitstellen, indem Sie yarn docs:dev wie unten gezeigt.

yarn docs:dev
yarn run v1.22.19
$ vitepress dev docs
vitepress v1.0.0-alpha.21

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose

VitePress unterstützt "hot-reloading", was bedeutet, dass Sie nach dem Speichern einer Datei im Projekt die Website nicht neu aufbauen müssen, um Ihre Änderungen zu sehen.

Jetzt sollte ein Server laufen, der normalerweise an folgendem Ort läuft: http://localhost:5173.

helloworld.gif

Herzlichen Glückwunsch! Unsere App läuft jetzt, und Sie können bereits einige der Eigenschaften und Funktionen bemerken, die wir mit VitePress erhalten haben, wie zum Beispiel:

• Responsive Website mit Animationen

• Bauen nach der "Mobile-first"-Philosophie

• Integrierter Dunkel- und Lichtmodus

Hinzufügen weiterer Seiten und Verstehen der Dateistruktur

Fügen wir nun eine weitere Seite hinzu, zu der der Endbenutzer navigieren kann, sobald die Website geladen ist. Erstellen Sie zunächst eine Datei namens another-page.md innerhalb des Ordners docs Ordner. Fügen Sie den folgenden Text zum Inhalt der Datei hinzu # Another Page.

Jetzt sollte Ihr docs Ordner sollte nun wie folgt aussehen.

docs
├── index.md
├── another-page.md

Sie werden es nicht finden, wenn Sie versuchen, zu another page.md in Ihrem Webbrowser aufrufen. Sie können die Seite manuell aufrufen, indem Sie der URL folgen: http://localhost:5173/another-page.

Hinweis: Beachten Sie, dass die Verzeichnisstruktur mit dem URL-Pfad übereinstimmt.

Wie können wir das also beheben?

Hinzufügen der Navigation

Wir haben die Grundlagen einer Website, aber es fehlt an Navigationsmöglichkeiten, um die anderen Seiten zu finden. Normalerweise wird das Seitenleistenmenü für Dokumentationswebsites verwendet. Um sie hinzuzufügen, müssen wir zunächst ein paar Dinge tun.

Um die Navigation Ihrer Website anzupassen und hinzuzufügen, erstellen wir zunächst ein .vitepress Verzeichnis innerhalb Ihres docs Verzeichnis. Fügen Sie anschließend eine weitere Datei namens config.js. In diesem Ordner werden alle VitePress-spezifischen Konfigurationsdateien abgelegt. Ihre Projektstruktur sollte wie folgt aussehen:

docs
├── index.md
├── another-page.md
└── .vitepress
    └── config.js

Öffnen Sie Ihre vitepress/config.js und fügen Sie den folgenden Code ein:

export default {
  title: 'VitePress',
  description: 'Vonage Loves Developers.'
}

Dadurch werden ein Standardtitel und eine Standardbeschreibung für die Website erstellt, die von den Suchmaschinen indiziert werden.

Als Nächstes konfigurieren wir unsere Navigationsleiste auf der obersten Ebene so, dass sie zwei zusätzliche Elemente für unsere Fahrplan und Möglichkeiten für unsere Benutzer zu Feedback. Fügen Sie das Folgende in Ihre vitepress/config.js Datei nach dem description Feld.

themeConfig: {
 nav: [
  { text: 'Roadmap', link: '/roadmap' },
  { text: 'Feedback', link: '/feedback' }
]

toplevelnavigation.png

Großartig! Unsere Website nimmt Gestalt an! Fügen wir nun unsere Seitenleiste unterhalb des nav Element, das wir gerade erstellt haben.

export default {
  title: 'VitePress',
  description: 'Vonage Loves Developers.',
  themeConfig: {
    nav: [
      { text: 'Roadmap', link: '/roadmap' },
      { text: 'Feedback', link: '/feedback' }
    ],
    sidebar: [
      {
        text: 'Guide',
        items: [
          { text: 'Introduction', link: '/introduction' },
          { text: 'Getting Started', link: '/getting-started' },
        ]
      }
    ]
  }
}

Jetzt nimmt unsere Website langsam Form an! Wir haben eine Top-Level- und eine Sidebar-Navigation hinzugefügt. Wir haben auch eine Nächste Seite Schaltfläche, die zur Einführung Seite führt (sobald wir sie erstellt haben).

sidelevelnavigation.png

Fügen wir nun alle Seiten hinzu, die wir gerade erstellt haben:

Erstellen Sie die folgenden Dateien mit den Namen roadmap.md, feedback.md, introduction.md und getting-started.md im Ordner docs und geben Sie ihnen eine Überschrift mit demselben Namen.

Zum Beispiel, # Roadmap in die Datei roadmap.md Datei eingegeben. Machen Sie das für alle Dateien.

Sobald Sie alles gespeichert haben, kehren Sie zu Ihrer Website zurück, um zu prüfen, ob alle Links nun wie vorgesehen funktionieren.

navigationadded.gif

Andere bemerkenswerte Merkmale

GitHub oder GitLab Links bearbeiten

Sie können auf jeder Seite automatisch einen Link erstellen, über den Ihre Leser über Git-Verwaltungsdienste wie GitHub oder GitLab zur Genauigkeit der Seite beitragen können. Um dies zu aktivieren, fügen Sie themeConfig.editLink Optionen zu Ihrer Konfiguration hinzu, wie unten gezeigt:

export default {
  themeConfig: {
    editLink: {
      pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path',
      text: 'Edit this page on GitHub'
    }
  }
}

Jede gerenderte Seite enthält nun einen Link zu GitHub (oder GitLab), über den der Benutzer eine Pull-Anfrage stellen kann.

editpage.png

Kundenspezifische Container

Es gibt eine integrierte Unterstützung für benutzerdefinierte Container, wenn Sie einen Leser auf etwas hinweisen möchten, z. B. auf eine Info, einen Tipp, einen Warnhinweis usw.

::: info
This is an info box.
:::

::: tip
This is a tip.
:::

::: warning
This is a warning.
:::

::: danger
This is a dangerous warning.
:::

::: details
This is a details block.
:::

Dies wird wie folgt wiedergegeben:

tipbox.png

Syntaxhervorhebung in Codeblöcken

Die Syntaxhervorhebung in Codeblöcken wird auf verschiedene Weise unterstützt. In diesem Beispiel sehen Sie, wie Sie eine Zeile in einem Codeblock hervorheben können:

export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}

syntaxhighlighting.png

Bereitstellen Ihrer App

Nachdem wir nun unsere statische Site entwickelt und ihr Seiten sowie eine umfangreiche Navigationsleiste hinzugefügt haben, können wir unsere App bereitstellen. Dazu führen Sie den folgenden Befehl aus yarn docs:build.

Wenn alles richtig funktioniert, sehen Sie Folgendes:

yarn docs:build
yarn run v1.22.19
$ vitepress build docs
vitepress v1.0.0-alpha.21
✓ building client + server bundles...
⠋ rendering pages...(node:3164) ExperimentalWarning: The Fetch API is an experimental feature. This feature could change at any time
(Use `node --trace-warnings ...` to show where the warning was created)
✓ rendering pages...
build complete in 8.29s.
Done in 8.97s.

Die gerenderten Dateien werden standardmäßig auf Ihrer Projektseite unter dist. Meine Dateien wurden zum Beispiel hier gerendert: C:\Users\mbcru\source\static-starter\docs\.vitepress\dist

fileexplorer.png

Nachbereitung

Jetzt, wo Ihre statische Website läuft, können Sie spezifische Kommunikationsfunktionen hinzufügen, die Vonage bietet, wie zum Beispiel die Videooder Nachrichtenübermittlung, etc. Möglichkeiten!

Wenn Sie Fragen oder Feedback haben, besuchen Sie den Vonage Entwickler-Slack oder senden Sie mir einen Tweet auf Twitterund ich werde auf Sie zurückkommen. Nochmals vielen Dank fürs Lesen, und wir sehen uns beim nächsten Mal!