Voraussetzungen

node.js und der Paket-Manager yarn müssen installiert sein. Praktisch ist natürlich auch eine IDE die Vue und Markdown unterstützt, z.B. Visual Studio Code.

Neues Projekt anlegen

1. ein neues Verzeichnis anlegen
2. im neuen Verzeichnis mit der Shell ein neues Projekt anlegen:

yarn init

3. Vitepress hinzufügen:

yarn add --dev vitepress

4. Ein Unterordner docs erstellen und darin eine Datei index.md mit dem folgendem Inhalt erstellen:

# Hallo VitePress
## Los geht's!

5. Der Datei package.json einige Skripte hinzufügen:

{
  "scripts": {
	"docs:dev": "vitepress dev docs",
	"docs:build": "vitepress build docs",
	"docs:serve": "vitepress serve docs"
  }
}

6. Die Seite im Dev-Modus mit einem lokalen Server starten:

yarn docs:dev

7. Die Seite im Browser unter http://localhost:3000 öffnen

Markdown einbauen

Im Docs-Ordner kann nun eine Datei-Struktur von md-Dateien angelegt werden. Es sind Unterverzeichnisse möglich. Name und Verzeichnis bestimmt den Link unter welchem der jeweilige Inhalt dann im Browser verfügbar ist. Einige Beispiele:

Pfad der Datei	URL im Browser
docs/index.md	https://localhost:3000/
docs/workshops.md	https://localhost:3000/workshops.html
docs/workshop/index.md	https://localhost:3000/workshop/
docs/workshop/vitepress.md	https://localhost:3000/workshop/vitepress.html

Frontmatter

Jede Markdown-Datei kann gewisse Zusatzinfos in einem Header speichern. Dazu verwendet Vitepress das Format YAML (steht für YAML Ain’t Markup Language). Z.B. kann die Startseite des Vitepress-Standard-Templates eine Liste von sogenannten Features darstellen:

---
title: Fata 2021 Informatik
home: true
heroText: FaTa2021
tagline: Informatik
actionText: Übersicht
actionLink: /programm
features:
  - title: Useless Machine
	details: Lass dich überraschen und inspirieren im Workshop von Marco Schmalz
  - title: Markdown und Vue
	details: Unterrichtsunterlagen mit Vitepress schreiben und veröffentlichen
  - title: Micro:bit
	details: kleiner Computer ganz gross – Workshop von Stefan Rothe und Martin Lehmann
---

Der YAML-Header muss das erste Element in der Markdown-Datei sein! Deshalb wohl auch der Name *Frontmatter. Mehr infos im offiziellen Guide.

Konfiguration

Die Konfigurations-Datei des Projektes ist docs/.vitepress/config.js. Darin werden Site-spezifische Infos gespeichert, aber auch die Konfiguration des Markdown-Renderers und dessen Erweiterungen:

module.exports = {
	lang: "de-CH",
	title: "FS IN Kanton Bern",
	description: "",
	markdown: {
		lineNumbers: true,
		breaks: true,
		typographer: true,
		quotes: "«»‹›",
		linkify: true,
		config: (md) => {
  			md.use(require("markdown-it-multimd-table"), {
				headerless: true,
				rowspan: true,
  			});
  			md.use(require("markdown-it-deflist"));
		},
	},
};

Mehr Infos in der offiziellen Referenz.

Navigation

Vitepress bietet zwei Navigations-Bereich an: oben rechts in der sogenannte Navbar und links vom Inhalt in der Sidebar. Beide Bereiche werden über die Datei docs/.vitepress/config.js mit JSON gesetzt. Hier ein Beispiel:

themeConfig: {
	nav: [
  		{ text: "Home", link: "/" },
  		{
			text: "Workshops",
			link: "/workshops",
  		}
	],
	sidebar: {
		"/workshop/": [
			{
				text: "Programm",
				link: "/programm",
			},
			{
				text: "Workshops",
				link: "/workshops",
			}	
		],		
  		"/": [
			{
	  			text: "Programm",
	  			link: "/programm",
			},
			{
	  			text: "Workshops",
	  			link: "/workshops",
			}
  		],
	},
},

Es sind mehrere Sidebars möglich, je nachdem in welchem Unterverzeichnis der User sich gerade befindet. Im Beispiel workshop oder / (root). Zudem werden in der Sidebar die Unterkapitel der aktuellen Seite automatisch eingeblendet.

Vue-Komponenten verwenden

auf einer Seite

Vue 3 bringt ein neues Feature mit für Single File Components und die neue Composition API: das sogenannte «Setup-Script». Dieses lässt sich in Vitepress direkt in der Markdown-Datei einsetzen um eine Vue-Component zu laden. Am besten direkt nach dem YAML-Header einbauen:

<script setup>
import Dice from "./Dice.vue"
</script>

Nun kann irgendwo weiter unten die Komponente im Inhalt integriert werden:

• Markdown
• Vorschau

<Dice />

global

Globale Komponenten können in der enhanceApp-Funktion in der Datei vitepress/theme/index.js registriert werden:

import DefaultTheme from 'vitepress/theme'

export default {
  ...DefaultTheme,
  enhanceApp({ app }) {
	app.component('./components/Dice', Dice)
  }
}

Grafische Anpassungen

In derselben Datei lässt sich eine eigene CSS-Datei importieren:

docs/.vitepress/theme/index.js

import DefaultTheme from "vitepress/theme";
import "./custom.css";

export default DefaultTheme;

Nun kann man in der Datei docs/.vitepress/theme/custom.css gewisse Anpassungen vornehmen. Z.B. liessen sich die Farben anpassen (CSS-Variablen) und der Header etwas farbiger machen:

/* Farben */
:root {
  --c-brand: #f26803;
  --c-brand-light: #f26803;
}
a {
  color: #3bb5ce;
}
h2 {
  border-color: #89ac10;
}

/* Header */
header.nav-bar {
  background-color: #3bb5ce !important;
}	
.nav-bar-title {
  color: white !important;
}

Mehr Infos im offiziellen Guide.

Seite Veröffentlichen

Zum Veröffentlichen startet man einen Build aus der Shell:

yarn docs:build

Wenn alles klappt und es keine Fehler gibt, so erhält man im Ordner docs/.vitepress/dist sämtliche Dateien der Webseite. Diese kann man nun per SFTP, SSH oder wie auch immer auf einen Server laden und veröffentlichen.

Mit dem eingebauten Server lässt sich auch die fertige Webseite aus dem dist-Ordner lokal angucken (natürlich ohne Hot-Reload):

yarn docs:serve