CSS personnalisé

Les thèmes Jamdesk fournissent des valeurs par défaut adaptées, mais vous pouvez ajouter du CSS personnalisé pour correspondre à votre marque ou ajuster des styles précis.

Ajouter du CSS personnalisé

Créez un fichier style.css à la racine de votre projet (le même dossier que votre docs.json). Jamdesk l'applique automatiquement à chaque page ; aucune entrée docs.json n'est nécessaire.

Tout fichier .css à la racine du projet fonctionne, pas seulement style.css, ce qui est pratique lors d'une migration depuis un autre outil. S'il y en a plusieurs, Jamdesk les combine par ordre alphabétique du nom de fichier.

Exécutez jamdesk dev pour prévisualiser le résultat en local. Le rendu de votre CSS personnalisé y est identique à celui du site publié.

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

Pour un tutoriel plus détaillé qui recolore l'en-tête et ajoute un bouton flottant, consultez Exemples CSS et JS.

Variables CSS

Les couleurs et les rayons de bordure proviennent de variables CSS. Remplacez-les sur :root et tous les composants qui les utilisent suivent :

: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;
}

Les valeurs ci-dessus sont les valeurs par défaut du thème Jam. Les autres thèmes partent de leurs propres valeurs, et vous pouvez toutes les lire dans les outils de développement de votre navigateur, sur l'élément <html>.

Les couleurs de votre marque se définissent dans docs.json, pas ici. Jamdesk transforme colors.primary en couleur d'accent utilisée pour les liens, les boutons et l'élément actif de la barre latérale. Consultez Couleurs personnalisées.

Les polices se définissent aussi dans docs.json. Le champ fonts charge une police Google Fonts ou votre propre fichier de police et l'applique partout. Définir font-family en CSS ne fonctionne qu'avec !important, car les thèmes définissent les polices avec des sélecteurs plus spécifiques. Consultez Typographie.

Personnalisations courantes

Changer la police du code

Les blocs de code conservent la police monospace du thème, sauf si vous la remplacez avec !important :

@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;
}

Personnaliser le style des liens

Les liens dans le corps de la page ont toujours des classes. Sélectionnez-les donc selon leur emplacement, et non avec a:not([class]) :

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

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

Ajuster l'espacement des titres

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

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

Styliser les encarts

Les encarts tirent leurs couleurs de variables se terminant par -bg, -border et -text :

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

Styliser l'onglet actif

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

Mode sombre

Jamdesk ajoute la classe dark à <html> en mode sombre. Placez les remplacements du mode sombre sous html.dark :

/* 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;
}

Sélecteurs à utiliser

Les noms de classe de Jamdesk proviennent de Tailwind et peuvent changer à chaque version. Ces points d'accroche sont stables :

Polices externes

Chargez les polices via docs.json chaque fois que possible. Le champ fonts gère les polices Google Fonts et les fichiers auto-hébergés, y compris les fichiers .woff2 de votre dépôt, et les applique aux titres et au texte courant.

Le CSS sert de solution de repli pour tout ce que fonts ne couvre pas, comme la police du code ci-dessus ou une police différente sur un seul élément. Chargez la police avec @import ou @font-face, puis définissez-la avec !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;
}

Styles responsifs

Utilisez des media queries pour les ajustements selon la taille de l'écran :

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

Débogage

Faites un clic droit sur un élément et choisissez Inspect pour trouver ce qu'il faut cibler. Préférez les points d'accroche de Sélecteurs à utiliser, les rôles comme role="tab" et les variables CSS aux longs noms de classe Tailwind. Si une règle ne s'applique pas, vérifiez dans le panneau Styles s'il existe une règle du thème qui l'emporte par sa spécificité ou qui utilise !important.

Limitations

• Le CSS s'applique globalement ; utilisez des sélecteurs spécifiques pour éviter les conflits
• Certains styles du thème, dont les polices et l'arrière-plan de l'en-tête du thème Jam, utilisent !important ou des sélecteurs très spécifiques, ce qui peut vous obliger à utiliser !important pour les remplacer
• En prévisualisation locale (jamdesk dev), les modifications de vos fichiers CSS s'appliquent au rechargement du navigateur ; sur votre site publié, les changements prennent effet au prochain build

Et ensuite ?