Tippe, um Seiten und Abschnitte zu finden.

Zum Inhalt
Ginko

Komponenten

Das Paket @lupinum/ginko-components mit Registry, Vue-Komponenten und Modul. Jede Komponente mit Beispiel und Markdown-Quelltext.

Was das Paket bringt

@lupinum/ginko-components liefert Bausteine für Markdown-Text: Hinweise, Reiter, Karten, Code-Gruppen, Video, Quiz und mehr. Das Paket hat drei Teile:

  • Die Registry. Das sind reine Daten, ohne Vue. Sie sagt, welche Tags es gibt, welche Props sie haben und wo sie stehen dürfen. Deine ginko.config.ts lädt sie in Node.
  • Die Vue-Komponenten. Sie zeichnen die Tags. Alle Klassen beginnen mit ginko-. Die Farben kommen aus den shadcn-Tokens deiner Seite (siehe Gestaltung).
  • Das Nuxt-Modul. Es verbindet jeden Tag mit seiner Komponente. <GinkoMarkdown> nutzt diese Zuordnung von selbst.

Diese Seite zeigt jede Komponente live. Unter jedem Beispiel steht der Markdown-Text, aus dem es entsteht, und danach die Liste der Props. Die README des Pakets hat dieselben Listen als Tabellen.

Einrichten

Du brauchst drei Schritte.

Paket installieren

Terminal
npm install @lupinum/ginko @lupinum/ginko-i18n @lupinum/ginko-components

Modul eintragen

Das Modul gehört in die nuxt.config.ts:

ts
export default defineNuxtConfig({
  modules: ['@lupinum/ginko/nuxt', '@lupinum/ginko-components'],
})

Mit der Ebene @lupinum/ginko-docs brauchst du weder das Paket noch den zweiten Eintrag: Die Ebene bringt beides mit, und components kommt auch aus @lupinum/ginko-docs/config. Das Modul braucht @lupinum/ginko/nuxt für seine Texte; ohne es bricht der Build ab und sagt das.

Registry an defineSite geben

ts
import { defineSite } from '@lupinum/ginko'
import { components } from '@lupinum/ginko-components/registry'

export default defineSite({
  // …
  components,
})

Mit components prüft Ginko das Markdown der Seiten streng. Ein unbekannter Tag, eine unbekannte Prop oder ein unbekannter Bereich (Slot) lässt den Build fehlschlagen. Ein Tippfehler wie ::callot fällt so beim Build auf und nicht erst bei den Lesern. Ohne components lehnt der Parser Slots ab, und ein Komponenten-Tag nimmt nur title, lang, dir und aria-*: Andere Props lehnt er ab, und die Seite lässt sie weg.

Props schreiben

Props stehen in geschweiften Klammern nach dem Tag: ::card{title="Garten" iconColor="primary"}. Schreib jeden Namen genau wie in den Listen auf dieser Seite. Namen aus zwei Wörtern sind camelCase (iconColor, defaultValue); icon-color ist eine unbekannte Prop. Eine Ja/Nein-Prop wirkt allein (open) oder mit "true" und "false".

Zwei Props gibt es bei vielen Tags:

  • icon nimmt einen Iconify-Namen wie lucide:book-open; ein Name ohne Präfix meint Lucide. Es erscheint über <Icon> von @nuxt/icon, das in der Doku-Ebene steckt. Es gehen nur Symbolsätze, die deine Seite installiert. Hinweise kennen außerdem sechs eingebaute Namen (siehe callout).
  • appearance ist quiet oder tint (siehe Darstellung).

Eine Komponente ersetzen

<GinkoMarkdown> hat die Prop :components. Ein Tag, den du dort angibst, gewinnt gegen die Zuordnung des Moduls, und zwar je Tag. Alle anderen Tags bleiben, wie sie sind.

vue
<script setup lang="ts">
import MyCallout from '~/components/MyCallout.vue'

const route = useRoute()
const doc = useGinkoEntry('docs', () => route.params.slug)
</script>

<template>
  <GinkoMarkdown :value="doc.data.body" :components="{ callout: MyCallout }" />
</template>

Die Vue-Komponenten des Pakets kommen aus @lupinum/ginko-components/components. So kannst du zum Beispiel Callout in deiner Variante umhüllen, statt sie neu zu schreiben.

Eine eigene Komponente hinzufügen

Deine Seite kann neben den Tags des Pakets eigene Tags haben. Beschreib jeden mit defineComponents und nimm ihn in die Registry auf. Dann kennt die strenge Prüfung seine Props, und der Editor bietet ihn an.

ts
// ginko.config.ts
import { defineComponents, defineSite, f } from '@lupinum/ginko'
import { components } from '@lupinum/ginko-components/registry' // mit der Doku-Ebene: aus '@lupinum/ginko-docs/config'

const own = defineComponents({
  pricing: {
    kind: 'block',
    label: { de: 'Preis', en: 'Price' },
    describe: { de: 'Ein Preis mit Titel, darunter der Text.', en: 'A price with a title, the text below.' },
    props: {
      title: f.text({ de: 'Titel', en: 'Title' }, { max: 80 }),
      price: f.text({ de: 'Preis', en: 'Price' }, { max: 20 }),
    },
    editor: { example: '::pricing{title="Basis" price="9 €"}\nEine Seite, eine Sprache.\n::' },
  },
})

export default defineSite({
  // …
  components: { ...components, ...own },
})

Ein Tag ist kleingeschrieben mit Bindestrichen; eine Prop ist camelCase, beginnt nicht mit on und heißt nicht as, innerHTML, outerHTML, innerText, outerText oder textContent. Props können text, longtext, number, boolean, choice, choices, image oder ref sein. Hat dein Tag den Namen eines Tags aus dem Paket, gewinnt dein Eintrag in der Registry: Die Prüfung und der Editor nehmen deine Props. Gezeigt wird aber weiter die Komponente des Pakets, denn die Liste des Moduls gewinnt über globale Komponenten. Deine eigene Vue-Komponente für so einen Tag gibst du mit <GinkoMarkdown :components> an (siehe Eine Komponente ersetzen). Eine globale Komponente wirkt nur für Tag-Namen, die das Paket nicht nutzt.

Dann fehlt die Vue-Komponente. Ginko sucht eine globale Komponente mit dem Namen des Tags in PascalCase, aus pricing wird also app/components/global/Pricing.vue. Die Props kommen als Text an, der Inhalt als Standard-Slot:

vue
<script setup lang="ts">
defineProps<{ title: string; price: string }>()
</script>

<template>
  <section class="pricing">
    <h3>{{ title }} <span>{{ price }}</span></h3>
    <slot />
  </section>
</template>

Texte der Oberfläche ändern

Feste Texte, zum Beispiel „Code kopieren“, „Abspielen“ oder die Quiz-Knöpfe, liegen in den Sprachdateien des Pakets unter dem Namensraum components. Sie folgen der Sprache der Seite. Eine Seite überschreibt einen Schlüssel in ihrer eigenen i18n/<code>.json:

json
{ "components": { "code": { "copy": "Kopieren" } } }

Eine Komponente in die eigene App kopieren (shadcn-vue)

Das npm-Paket ist der einfache Weg: Updates kommen mit dem Paket. Wenn du den Code einer Komponente selbst besitzen und ändern willst, kopierst du sie mit der CLI von shadcn-vue in deine App. Diese Seite stellt die Registry bereit:

Terminal
npx shadcn-vue@latest add https://ginko.lupinum.com/r/callout.json

Die CLI schreibt die Komponente und ihre Hilfsdateien nach components/ginko/ und installiert die npm-Pakete, die sie brauchen. Die Namen der Einträge sind die Dateinamen in Kebab-Case (callout, code-block, timeline-item); /r/registry.json listet alle. Binde das Stylesheet einmal in dein Haupt-CSS ein:

css
@import "./components/ginko/ginko-components.css";

Hinter einer kopierten Komponente steht kein Nuxt-Modul. Ihre Texte sind die englischen in components/ginko/texts.ts; dort änderst du sie.

Darstellung

Jede Komponente mit Rahmen ist ruhig (ein Rahmen) oder getönt (eine Fläche). Hinweise und Zitate sind getönt, alles andere ruhig. appearance="quiet" oder appearance="tint" ändert eine einzelne Komponente; Karten folgen ihrer Gruppe. Im HTML wird daraus data-appearance.

Ruhig
Mit Rahmen, ohne Fläche.
Getönt
Mit Fläche, ohne Rahmen.

Für die ganze Seite setzt du zwei Tokens in deinem CSS:

css
:root { --ginko-surface: var(--muted); --ginko-surface-border: transparent; }

Gestaltung

Die Komponenten lesen die shadcn-Tokens deiner Seite: --background, --foreground, --card, --muted, --muted-foreground, --border, --primary, --primary-foreground, --ring, --radius und --font-mono. Jede Farbe muss ein ganzer Farbwert sein (oklch(…), hsl(…) oder Hex). Alte shadcn-Themes für Tailwind 3 speichern nur Zahlen (--muted: 210 40% 96%); damit gibt es hier keine Farbe. Ohne die Tokens nutzen die Komponenten neutrale Farben, die dem Farbmodus deiner Seite folgen: dunkel mit color-scheme: dark, der Klasse .dark oder data-theme="dark".

Diese Namen bleiben stabil; alles andere ist intern:

  • Tokens: --ginko-surface und --ginko-surface-border (siehe oben), --ginko-tint, die Hinweisfarben --ginko-info, --ginko-warning, --ginko-error, --ginko-success und --ginko-idea, und --ginko-scroll-margin (Abstand über einem API-Eintrag, zu dem ein Link springt).
  • Code steht immer auf einer dunklen Fläche: --ginko-code-frame, --ginko-code-bg, --ginko-code-fg, --ginko-code-muted und --ginko-code-hover.
  • Die Klasse ginko-<tag> am äußeren Element jedes Tags, zum Beispiel ginko-callout oder ginko-card, und das Attribut data-appearance. Ausnahmen: Der Codeblock (pre) hat ginko-code, ein Markdown-Bild ginko-img, collapse ohne title hat ginko-clip.

Hinweise

callout

Hebt einen Absatz als Hinweis hervor, mit Symbol und optionalem Titel. type wählt die Art: note, info (Standard), warning, error, success oder idea.

Achtung
Das gilt nur für neue Seiten.

Props: type, title, icon (einer von file-text, info, triangle-alert, circle-x, circle-check, lightbulb oder ein Iconify-Name), appearance.

note, info, warning, error, success, idea

Dieselben Kästen mit festem Typ. Du schreibst den Namen der Art statt callout.

Notiz
Ein kurzer Gedanke am Rand.
Gut zu wissen
Die Änderung gilt sofort.
Achtung
Das lässt sich nicht rückgängig machen.
Nicht möglich
Die Datei ist zu groß.
Geschafft
Die Seite ist veröffentlicht.
Tipp
Ein Foto macht die Seite lebendiger.

Props: title, icon, appearance, wie bei callout.

Text

aside

Eine ruhige Anmerkung neben dem Haupttext, mit optionaler Überschrift.

Props: title (die Überschrift), appearance.

excerpt

Ein hervorgehobenes Zitat oder Textauszug, mit optionaler Quelle. size="display" macht den Text groß.

Wer pflanzt, glaubt an morgen.
Anna Muster, 2024

Props: title, source, size (body Standard, display), appearance.

dropcap

Der erste Buchstabe des Absatzes wird groß dargestellt. lines setzt die Höhe in Zeilen (2 bis 4).

Es war einmal ein kleiner Garten am Rand der Stadt.

Props: lines (2 bis 4, Standard 2).

kbd

Zeigt eine Tastatureingabe als Taste. Das ist ein Inline-Tag: du schreibst ihn mit einem Doppelpunkt mitten im Satz.

Drücke Strg + S zum Speichern.

badge

Eine kleine farbige Marke im Text, zum Beispiel „neu“. Auch ein Inline-Tag. color ist neutral, primary, success, warning oder error.

Die Funktion ist neu.

Props: color (neutral Standard, primary, success, warning, error).

read-more

Ein auffälliger Link zu einer weiteren Seite, auf Wunsch mit Symbol (icon). Mehrere direkt hintereinander bilden eine Liste.

Zum EinstiegWie alles anfängt.
SprachenSeiten in mehreren Sprachen.

Props: href (Pflicht), title (ohne steht dort die Adresse), icon, appearance.

inline-toc

Listet die Überschriften der Seite als Links auf. Es bleibt zugeklappt, bis jemand es öffnet; open zeigt die Liste sofort. Ohne Überschriften zeigt es nichts. Hier listet es die Abschnitte dieser Seite:

Auf dieser Seite
md
::inline-toc{title="Auf dieser Seite" depth="2"}
::

Props: title, depth (2 bis 4: bis zu welcher Überschriftenebene), open, appearance.

Layout

flow

Hält den Text in einer angenehmen Zeilenlänge, auf Wunsch mit Hintergrund (background: none, muted, tint).

Ein längerer Text, der in Lesebreite steht.

Props: width (reading Standard, wide), background (none Standard, muted, tint).

layout, column

Ordnet Spalten nebeneinander an; auf kleinen Bildschirmen stehen sie untereinander. layout ist der Rahmen, column eine Spalte. width an der Spalte setzt die Breite.

Breite Spalte
Schmale Spalte

Props von layout: frame (none Standard, card, border, border-dashed, outline, outline-dashed), align (start, center, end), gap (none, sm, md Standard, lg), stack (sm, md Standard, lg: ab welcher Breite die Spalten nebeneinander stehen), background (none Standard, muted, tint).

Props von column: width (xs bis xl, Standard md), align (start, center, end), fit (natural Standard, cover, contain: wie ein Bild die Spalte füllt).

center

Zentriert den Inhalt in einer schmalen Spalte, auf Wunsch mit Rahmen (frame="card" und andere).

Bis bald!

Props: width (sm, md Standard, lg), frame (wie bei layout).

timeline, timeline-item

Eine senkrechte Liste von Ereignissen in zeitlicher Reihenfolge. active hebt ein Ereignis hervor, icon zeigt ein Symbol statt des Punkts.

Gründung

2024
Der Verein startet.

Neuer Garten

2026
Die zweite Fläche ist offen.

timeline hat keine Props. Props von timeline-item: date, meta, title, icon, active.

steps

Nummerierte Schritte; jede Überschrift im Block beginnt einen Schritt. mode="check" zeigt Haken statt Zahlen.

Konto anlegen

Öffne die Startseite.

Seite füllen

Trage die Texte ein.

Props: mode (numbered Standard, check), appearance.

cards, card

Ordnet Karten nebeneinander an (cols 1 bis 3). Eine Karte hat Titel, Text und auf Wunsch Symbol (icon, gefärbt mit iconColor), Bild und Link.

Erste Karte

Kurzer Text. Links darin gehen auch: Sprachen.

Zweite Karte

Noch ein Text.

Props von cards: cols (1 bis 3, Standard 2), appearance.

Props von card: title, description, footer, href (die ganze Karte wird zum Link), icon, iconColor (primary, info, success, warning, error), image, imageWidth und imageHeight (seine Größe in Pixeln; Ginko füllt sie aus der Datei), horizontal (Bild neben dem Text), appearance.

Interaktiv

tabs, tab

Zeigt mehrere Inhalte als Reiter, von denen immer einer sichtbar ist. Der erste ist vorgewählt, icon setzt ein Symbol vor den Namen. Die Reiter lassen sich per Tastatur bedienen. variant="line" unterstreicht den gewählten Reiter und lässt den Rahmen weg; padded="false" lässt einen Codeblock den Reiter füllen. Ohne JavaScript ist nur der erste Reiter zu sehen.

Leser finden übersetzte Seiten mit Suche.
12 € im Monat.

Props von tabs: variant (separate Standard, line), padded (Standard an), appearance. Props von tab: title (Pflicht), icon.

accordion, accordion-item

Eine Liste von Einträgen, die sich einzeln aufklappen lassen. Öffnen eines Eintrags schließt die anderen; multiple lässt mehrere offen. Sie nutzt <details> und funktioniert auch ohne JavaScript.

Wie melde ich mich an?
Per E-Mail mit einem Code.
Kostet das etwas?
Nein.

Props von accordion: multiple, appearance. Props von accordion-item: title (Pflicht), open.

collapse

Mit title ein Bereich mit Überschrift, den Leser auf- und zuklappen.

Mehr Details
Hier steht der längere Text.

Ohne title wird langer Inhalt, meist ein Codeblock, gekürzt; „Alle … Zeilen anzeigen“ öffnet ihn ganz. Das Beispiel ist die ginko.config.ts dieser Seite.

ginko.config.ts
// The Ginko docs. Every page comes from Markdown in content/docs; the layout,
// search and components come from @lupinum/ginko-docs. This site never asks the platform.
import { defineSite } from '@lupinum/ginko'
import { blogCollections, blogPages, changelogCollection, changelogPages, components, docsCollection, docsHome } from '@lupinum/ginko-docs/config'

const locales = ['de', 'en'] as const

export default defineSite({
  site: 'ginko-docs',
  name: 'Ginko',
  url: 'https://ginko.lupinum.com',
  timeZone: 'Europe/Vienna',
  locales,
  currency: 'EUR',
  pages: { home: { de: '/', en: '/en' }, blog: blogPages({ locales }), changelog: changelogPages({ locales }) },
  components,
  bricks: { home: docsHome(), docs: docsCollection({ locales }), ...blogCollections({ locales }), changelog: changelogCollection() },
})

Props: title, open (mit title: von Anfang an offen), appearance.

Code

code-group

Zeigt mehrere Codeblöcke als Reiter, benannt nach Dateiname oder Sprache.

npm install @lupinum/ginko

code-group hat keine Props. Jeder Codeblock in Markdown, auch außerhalb einer Gruppe, zeigt Dateinamen oder Sprache und einen Kopierknopf.

code-tree

Zeigt einen Dateibaum und daneben den Code der gewählten Datei. Jeder Codeblock braucht den Pfad als Dateinamen.

<template><NuxtPage /></template>

Props: file (Pfad der Datei, die zuerst offen ist), expandAll (alle Ordner offen).

files

Zeigt Dateien und Ordner als Liste. Eine eingerückte Liste ergibt einen Ordner, Text nach # eine Notiz am Ende der Zeile. Bekannte Dateiarten bekommen ihr Symbol.

  • app
    • app.config.tsName und Logo
    • app.vue
    • components
      • Header.vue
  • content
    • index.md
  • nuxt.config.ts
  • package.json

Props: active (Pfad des Eintrags, der markiert wird), appearance.

Medien

figure

Ein Bild mit Bildunterschrift. Ein Klick vergrößert das Bild. alt ist Pflicht. Normale Markdown-Bilder (![alt](src)) laden ebenfalls erst bei Bedarf.

Das Zeichen von Ginko
Das Ginko-Blatt

Das Zeichen von Ginko

Props: src und alt (Pflicht), caption, width, height, bleed (breiter als der Text), aspect (auto Standard, square 1:1, landscape 4:3, portrait 3:4, video 16:9, wide 2:1), fit (cover Standard, contain), placement (inline Standard, start, end: neben dem Text), frame (border Standard, none), zoom (Standard an).

Ein Bild aus der Dateien-Bibliothek bringt seine kleineren Kopien mit, und der Browser lädt die kleinste, die scharf genug ist. Beim Zuschneiden auf ein Seitenverhältnis bleibt sein Fokuspunkt sichtbar: Du setzt ihn in der Bibliothek mit einem Klick ins Bild, und er gilt überall, wo das Bild steht. Vergrößert zeigt die Abbildung immer das ganze Bild. Das ältere Prop focus (top, bottom, left, right) wirkt in bestehenden Texten weiter, der Editor bietet es nicht mehr an.

video

Ein YouTube-, Vimeo- oder Video-Link. Von YouTube oder Vimeo wird erst nach einem Klick auf „Abspielen“ etwas geladen: kein iframe, kein Vorschaubild. Mit poster zeigst du ein eigenes Bild.

Beim Abspielen lädt YouTube Inhalte und setzt ggf. Cookies.

Props: src (Pflicht: ein YouTube- oder Vimeo-Link oder eine .mp4- oder .webm-Datei), title (Pflicht), poster, start (Sekunden).

embed

Eine Karte, ein Musik-Player oder ein Buchungs-Widget von einem bekannten Anbieter. Wie bei video lädt vor dem Klick nichts: Besucher sehen dein poster oder eine neutrale Fläche, einen Knopf und eine Zeile, die den Anbieter nennt. Eine Adresse, die kein Anbieter kennt, wird ein normaler Link. Ginko zeichnet dabei nie das HTML-Element embed oder iframe aus deinem Markdown: ::embed ist immer diese Komponente.

Beim Laden lädt OpenStreetMap Inhalte und setzt ggf. Cookies.

Props: src (Pflicht: die Adresse, die der Anbieter zum Einbetten gibt), title (Pflicht: Beschriftung des Knopfs und Titel des Rahmens), poster.

Anbieter

Eingebaut:

IdAdresseWo du sie bekommst
google-mapshttps://www.google.com/maps/embed?pb=…Google Maps: Teilen → Karte einbetten
openstreetmaphttps://www.openstreetmap.org/export/embed.html?…openstreetmap.org: Teilen → HTML
spotify, spotify-listhttps://open.spotify.com/track/… (auch episode, album, playlist, show)Der Link des Titels oder der Liste
calendlyhttps://calendly.com/<user>/<event>Der Link deiner Buchungsseite

In der nuxt.config.ts fügst du einen Anbieter hinzu, ersetzt einen oder schaltest einen ab:

ts
export default defineNuxtConfig({
  ginkoComponents: {
    embeds: {
      providers: {
        peertube: {
          name: 'PeerTube',
          pattern: '^https://peertube\\.example\\.org/w/([\\w-]+)$',
          embed: 'https://peertube.example.org/videos/embed/$1',
          allow: 'fullscreen',
        },
        spotify: false,
      },
    },
  },
})

name steht in der Zeile vor dem Klick. pattern ist ein regulärer Ausdruck für die ganze Adresse und muss mit ^https:// beginnen. embed ist die Adresse des Rahmens, mit $1 für die erste Gruppe des Musters, und muss mit https:// beginnen. ratio setzt die Form (Standard 16/9), height eine feste Höhe in Pixeln, allow das allow-Attribut des Rahmens. Der erste passende Anbieter gewinnt. Ein fehlerhafter Anbieter stoppt den Build mit einer Meldung, die ihn nennt.

Nimm nur Anbieter auf, denen du vertraust: Jeder Anbieter erlaubt Redakteuren, diese Seite in einem Rahmen auf deinen Seiten zu zeigen.

Lernen

quiz, quiz-question

Fragen zur Selbstkontrolle. Die Fragen erscheinen nacheinander, am Ende steht das Ergebnis. Es werden keine Daten gesendet. Die Antworten sind eine Aufgabenliste: - [x] ist richtig, - [ ] ist falsch. Die Erklärung steht im Bereich #explanation und erscheint erst nach dem Prüfen.

Kurz geprüft

Zwei Fragen zum Garten.

Wann gießt man am besten?
Frage 1 von 2

Props von quiz: title, description, appearance. Props von quiz-question: question (Pflicht), mode (single Standard: eine richtige Antwort, multiple: eine oder mehrere).

API

api, api-param

Beschreibt eine HTTP-Schnittstelle: Methode und Pfad, darunter die Parameter und Felder. Parameter mit gleicher group stehen zusammen, je Gruppe ein Reiter. Der Inhalt von api-param ist die Beschreibung.

GET/v1/gaerten
limit: number = 20seit 1.2
Anzahl der Einträge, höchstens 100.

Props von api: title, method (get, post, put, patch, delete, head, options), path, appearance. Props von api-param: name (Pflicht), group, type, required (zeigt eine Marke), deprecated, since, defaultValue.

Formeln und Diagramme

Formeln schreibst du mit $…$ im Text und mit $$…$$ als eigenen Block. Sie erscheinen mit KaTeX, schon im HTML vom Server: Die Fläche eines Kreises ist A=πr2A = \pi r^2.

∫01x2 dx=13\int_0^1 x^2 \, dx = \frac{1}{3}

Ein Code-Block mit der Sprache mermaid wird zum Diagramm. Es entsteht im Browser:

KaTeX und Mermaid werden nur geladen, wenn eine Seite sie braucht.