Benutzerdefiniertes CSS

Ergänze eigenes CSS zu den Theme-Standards, um dein Markendesign anzupassen oder bestimmte Stile zu verändern.

Eigenes CSS hinzufügen

Lege eine Datei style.css im Stammverzeichnis deines Projekts an (im selben Ordner wie deine docs.json). Jamdesk wendet sie auf jede Seite an. Ein Eintrag in docs.json ist nicht nötig.

Jede .css-Datei im Stammverzeichnis funktioniert, nicht nur style.css. Jamdesk kombiniert mehrere Dateien in alphabetischer Reihenfolge ihrer Dateinamen.

Führe jamdesk dev aus, um das Ergebnis lokal in der Vorschau zu sehen. Dein eigenes CSS wird dabei genauso dargestellt wie auf der veröffentlichten Seite.

/* Your custom styles */
article h1 {
  font-size: 2.5rem;
}

CSS- & JS-Beispiele zeigt, wie du die Kopfzeile neu einfärbst und eine schwebende Schaltfläche hinzufügst.

CSS-Variablen

Farben und Eckradien stammen aus CSS-Variablen. Überschreibe sie auf :root. Jede Komponente, die sie verwendet, übernimmt die Änderung:

:root {
  /* Page and text colors */
  --color-bg-primary: #ffffff;      /* page background */
  --color-bg-secondary: #f8fafc;    /* inputs, subtle panels */
  --color-text-primary: #0a0a0a;    /* headings */
  --color-text-secondary: #404144;  /* body text */
  --color-text-muted: #737373;      /* captions and hints */
  --color-border: #e2e8f0;

  /* Corner radius for cards, buttons and panels */
  --radius-sm: 6px;
  --radius-md: 8px;
  --radius-lg: 12px;
}

Die oben genannten Werte sind die Standardwerte des Jam-Themes. Andere Themes beginnen mit eigenen Werten. Du kannst sie in den Entwicklertools deines Browsers am Element <html> auslesen.

Deine Markenfarben gehören in docs.json, nicht hierher. Jamdesk wandelt colors.primary in die Akzentfarbe für Links, Schaltflächen und den aktiven Seitenleisten-Eintrag um. Siehe Eigene Farben.

Auch Schriften gehören in docs.json. Das Feld fonts lädt eine Google Font oder deine eigene Schriftdatei und wendet sie überall an. Eine font-family in CSS wirkt nur mit !important. Themes setzen Schriften mit spezifischeren Selektoren. Siehe Typografie.

Häufige Anpassungen

Schriftart für Code ändern

Codeblöcke behalten die Monospace-Schrift des Themes, sofern du sie nicht mit !important überschreibst:

@import url('https://fonts.googleapis.com/css2?family=Fira+Code&display=swap');

article pre,
article pre code,
article code {
  font-family: 'Fira Code', monospace !important;
  font-variant-ligatures: common-ligatures;
}

Linkstile anpassen

Links im Seitentext haben immer Klassen. Wähle sie nach ihrer Position aus, nicht mit a:not([class]):

article .prose a {
  text-decoration: underline;
  text-underline-offset: 3px;
}

article .prose a:hover {
  text-decoration-thickness: 2px;
}

Abstände bei Überschriften anpassen

article .prose h2 {
  margin-top: 3rem;
  margin-bottom: 1rem;
}

article .prose h3 {
  margin-top: 2rem;
  margin-bottom: 0.75rem;
}

Hinweisfelder gestalten

Hinweisboxen beziehen ihre Farben aus Variablen, die auf -bg, -border und -text enden:

/* Warmer Note callouts */
:root {
  --color-note-bg: #fef3c7;
  --color-note-border: #f59e0b;
}

Aktiven Tab gestalten

article [role="tab"][aria-selected="true"] {
  border-bottom-width: 3px;
}

Dunkler Modus

Jamdesk fügt im Dunkelmodus die Klasse dark zu <html> hinzu. Lege Überschreibungen für den Dunkelmodus unter html.dark ab:

/* Light mode */
:root {
  --color-bg-primary: #fffdf7;
}

.custom-banner {
  background: #f0f4ff;
  color: #1e3a5f;
}

/* Dark mode */
html.dark {
  --color-bg-primary: #14110f;
}

html.dark .custom-banner {
  background: #1e293b;
  color: #e2e8f0;
}

Zu verwendende Selektoren

Die Klassennamen von Jamdesk stammen von Tailwind und können sich mit jeder Version ändern. Diese Ansatzpunkte sind stabil:

Banner

Der Banner, den du in docs.json festlegst, hat eigene stabile Ansatzpunkte:

Setze die Farbvariablen auf .jd-banner, nicht auf :root. Die Typen warning und danger setzen eigene Werte direkt auf der Leiste, deshalb kommt ein Wert auf :root bei ihnen nicht an.

Eine einfache .jd-banner-Regel ändert jeden Typ:

.jd-banner {
  --jd-banner-bg: #111827;
  --jd-banner-fg: #f9fafb;
}

Mit dem Attribut änderst du nur einen Typ:

.jd-banner[data-type="danger"] {
  --jd-banner-bg: #7f1d1d;
}

Wenn dein CSS eine ältere Regel wie [data-jd-banner] { background: ... } enthält, färbt sie jeden Typ um, auch warning und danger. Ersetze sie durch eine der Regeln oben.

Mit --jd-banner-height hältst du deine eigenen Sticky-Elemente unter der Leiste. Ohne sichtbaren Banner ist die Variable nicht gesetzt, gib ihr also einen Fallback von 0px:

.my-sticky-toolbar {
  position: sticky;
  top: var(--jd-banner-height, 0px);
}

Externe Schriftarten

Lade Schriften möglichst über docs.json. Das Feld fonts lädt Google Fonts und selbst gehostete Dateien, einschließlich .woff2-Dateien in deinem Repository. Es wendet sie auf Überschriften und Fließtext an.

CSS ist der Ausweg für alles, was fonts nicht abdeckt, etwa die oben genannte Code-Schrift oder eine andere Schrift für ein einzelnes Element. Lade die Schrift mit @import oder @font-face und setze sie anschließend mit !important:

@font-face {
  font-family: 'CustomFont';
  src: url('/fonts/custom-font.woff2') format('woff2');
  font-weight: 400;
  font-display: swap;
}

article .prose blockquote {
  font-family: 'CustomFont', serif !important;
}

Responsive Stile

Verwende Media Queries für Anpassungen je nach Bildschirmgröße:

/* Phones */
@media (max-width: 768px) {
  article h1 {
    font-size: 1.75rem;
  }
}

Fehlerbehebung

Klicke mit der rechten Maustaste auf ein Element und wähle Untersuchen, um herauszufinden, was du ansprechen kannst. Bevorzuge die Ansatzpunkte aus Zu verwendende Selektoren, Rollen wie role="tab" und CSS-Variablen statt langer Tailwind-Klassennamen. Wenn eine Regel nicht greift, prüfe das Panel Styles auf eine Theme-Regel, die aufgrund der Spezifität gewinnt oder !important verwendet.

Einschränkungen

• CSS gilt global. Verwende spezifische Selektoren, um Konflikte zu vermeiden
• Einige Theme-Stile, darunter Schriften und der Hintergrund der Jam-Kopfzeile, verwenden !important oder sehr spezifische Selektoren. Möglicherweise brauchst du !important, um sie zu überschreiben
• Die lokale Vorschau (jamdesk dev) übernimmt Änderungen an deinen CSS-Dateien beim Neuladen des Browsers. Die veröffentlichte Seite übernimmt Änderungen beim nächsten Build

Wie geht es weiter?