Erste Schritte

Dieser Leitfaden führt Sie durch die Erstellung Ihrer ersten EmDash-Website, von der Installation bis zur Veröffentlichung Ihres ersten Beitrags.

Voraussetzungen

• Node.js v22.12.0 oder höher (ungerade nummerierte Versionen werden nicht unterstützt)
• npm, pnpm oder yarn
• Ein Code-Editor (VS Code empfohlen)

Neues Projekt erstellen

npm create emdash@latest

pnpm create emdash@latest

yarn create emdash

Folgen Sie den Anweisungen, um Ihr Projekt zu benennen und Ihre Einstellungen festzulegen.

Entwicklungsserver starten

Setup-Assistenten abschließen

Wenn Sie das Admin-Panel zum ersten Mal besuchen, führt Sie der Setup-Assistent von EmDash durch die Erstkonfiguration:

Sobald Ihr Passkey registriert ist, sind Sie angemeldet und werden zum Admin-Dashboard weitergeleitet.

Ihr erster Beitrag

Projektstruktur

Ihr EmDash-Projekt folgt einer Standard-Astro-Struktur mit einigen Ergänzungen:

my-emdash-site/
├── astro.config.mjs      # Astro + EmDash Konfiguration
├── src/
│   ├── live.config.ts    # Live Collections Konfiguration
│   ├── pages/
│   │   ├── index.astro   # Startseite
│   │   └── posts/
│   │       └── [...slug].astro  # Dynamische Beitragsseiten
│   ├── layouts/
│   │   └── Base.astro    # Basis-Layout
│   └── components/       # Ihre Astro-Komponenten
├── .emdash/
│   ├── seed.json         # Template-Seed-Datei
│   └── types.ts          # Generierte TypeScript-Typen
└── package.json

Konfigurationsdateien

astro.config.mjs

Die folgende Konfiguration registriert EmDash als Astro-Integration mit einer lokalen SQLite-Datenbank und lokalem Dateispeicher:

import { defineConfig } from "astro/config";
import emdash, { local } from "emdash/astro";
import { sqlite } from "emdash/db";

export default defineConfig({
	integrations: [
		emdash({
			database: sqlite({ url: "file:./data.db" }),
			storage: local({
				directory: "./uploads",
				baseUrl: "/_emdash/api/media/file",
			}),
		}),
	],
});

src/live.config.ts

Die folgende Datei verbindet EmDash über eine einzelne Live-Collection mit dem Content-System von Astro:

import { defineLiveCollection } from "astro:content";
import { emdashLoader } from "emdash/runtime";

export const collections = {
	_emdash: defineLiveCollection({ loader: emdashLoader() }),
};

Umgebungsvariablen

Für die Produktion generieren Sie einen Verschlüsselungsschlüssel für Plugin-Secrets mit folgendem Befehl:

npx emdash secrets generate

Fügen Sie den generierten Wert als EMDASH_ENCRYPTION_KEY zu Ihrer Umgebung hinzu, wie unten gezeigt. Dieser Schlüssel verschlüsselt Plugin-Secrets im Ruhezustand. Setzen Sie ihn jetzt, damit Ihre Bereitstellung bereit ist, wenn die Plugin-Secret-Verschlüsselung ihn verwendet.

EMDASH_ENCRYPTION_KEY=emdash_enc_v1_...

Der Schlüssel wird niemals in der Datenbank gespeichert — nur verschlüsselter Chiffretext wird gespeichert. Sichern Sie ihn an einem dauerhaften Ort, denn sein Verlust bedeutet den Verlust aller damit verschlüsselten Secrets.

Das Preview-HMAC-Secret und das Commenter-IP-Hash-Salt werden bei der ersten Verwendung generiert und in der Datenbank gespeichert, sodass Sie sie nicht setzen müssen. Überschreiben Sie das Preview-Secret nur, wenn ein separater Prozess dieselben Token wie Ihre Hauptwebsite verifizieren muss, wie unten gezeigt.

EMDASH_PREVIEW_SECRET=your-preview-secret

Inhalte in Seiten abfragen

Verwenden Sie die Abfragefunktionen von EmDash in Ihren Astro-Seiten. Diese folgen dem Live-Collections-Muster von Astro und geben { entries, error } für Collections und { entry, error } für einzelne Einträge zurück:

---
import { getEmDashCollection } from "emdash";
import Base from "../layouts/Base.astro";

const { entries: posts } = await getEmDashCollection("posts");
---

<Base title="Home">
  <h1>Neueste Beiträge</h1>
  <ul>
    {posts.map((post) => (
      <li>
        <a href={`/posts/${post.slug}`}>{post.data.title}</a>
      </li>
    ))}
  </ul>
</Base>

Die folgende Seite ruft einen einzelnen Eintrag per Slug ab:

---
import { getEmDashEntry } from "emdash";

const { slug } = Astro.params;
const { entry: post } = await getEmDashEntry("posts", slug);

if (!post) {
  return Astro.redirect("/404");
}
---

<h1>{post.data.title}</h1>

TypeScript-Typen generieren

Für vollständige Typsicherheit generieren Sie Typen aus Ihrem Datenbankschema:

npx emdash types

Dies erstellt .emdash/types.ts mit Interfaces für alle Ihre Collections. Ihr Editor vervollständigt nun Feldnamen automatisch und erkennt Typfehler.

Nächste Schritte

Mit der laufenden Website behandeln die folgenden Seiten, was als Nächstes zu tun ist:

• Kernkonzepte — Verstehen Sie, wie EmDash unter der Haube funktioniert
• Mit Inhalten arbeiten — Lernen Sie, Inhalte abzufragen und darzustellen
• Medienbibliothek — Bilder und Dateien hochladen und verwalten
• Blog erstellen — Erstellen Sie einen vollständigen Blog mit Kategorien und Tags
• Auf Cloudflare bereitstellen — Bringen Sie Ihre Website in die Produktion