CSS personalizado

Los temas de Jamdesk ofrecen valores predeterminados razonables, pero puedes añadir CSS personalizado para adaptarlos a tu marca o ajustar estilos específicos.

Añadir CSS personalizado

Crea un archivo style.css en la raíz de tu proyecto (la misma carpeta que tu docs.json). Jamdesk lo aplica automáticamente a todas las páginas; no se necesita ninguna entrada en docs.json.

Cualquier archivo .css en la raíz del proyecto funciona, no solo style.css, lo cual resulta útil al migrar desde otra herramienta. Cuando hay varios, Jamdesk los combina en orden alfabético según el nombre del archivo.

Ejecuta jamdesk dev para previsualizar el resultado localmente. Renderiza tu CSS personalizado de la misma forma que lo hace el sitio publicado.

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

Para un recorrido más largo que cambia el color del encabezado y añade un botón flotante, consulta Ejemplos de CSS y JS.

Variables CSS

Los colores y los radios de las esquinas provienen de variables CSS. Sobrescríbelas en :root y todos los componentes que las usan las seguirán:

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

Los valores anteriores son los predeterminados del tema Jam. Los demás temas parten de sus propios valores, y puedes consultarlos en las herramientas de desarrollo de tu navegador, en el elemento <html>.

Los colores de tu marca van en docs.json, no aquí. Jamdesk convierte colors.primary en el color de acento que se usa en los enlaces, los botones y el elemento activo de la barra lateral. Consulta Colores personalizados.

Las fuentes también van en docs.json. El campo fonts carga una Google Font o tu propio archivo de fuente y la aplica en todas partes. Definir font-family en CSS solo funciona con !important, porque los temas establecen las fuentes con selectores más específicos. Consulta Tipografía.

Personalizaciones comunes

Cambiar la fuente del código

Los bloques de código conservan la fuente monoespaciada del tema a menos que la sobrescribas con !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;
}

Personalizar los estilos de enlace

Los enlaces dentro del cuerpo de la página siempre tienen clases, así que selecciónalos por el lugar donde se encuentran, no con a:not([class]):

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

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

Ajustar el espaciado de los encabezados

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

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

Estilizar los callouts

Los callouts toman sus colores de variables que terminan en -bg, -border y -text:

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

Estilizar la pestaña activa

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

Modo oscuro

Jamdesk añade la clase dark a <html> en el modo oscuro. Coloca las sobrescrituras del modo oscuro bajo 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;
}

Selectores recomendados

Los nombres de clase de Jamdesk provienen de Tailwind y pueden cambiar en cualquier versión. Estos selectores son estables:

Fuentes externas

Carga las fuentes mediante docs.json siempre que puedas. El campo fonts admite Google Fonts y archivos alojados por ti, incluidos archivos .woff2 de tu repositorio, y los aplica a los encabezados y al texto del cuerpo.

El CSS es la alternativa para todo lo que fonts no cubre, como la fuente del código de arriba o una fuente distinta en un solo elemento. Carga la fuente con @import o @font-face y luego establécela con !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;
}

Estilos responsivos

Usa media queries para ajustes según el tamaño de pantalla:

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

Depuración

Haz clic derecho sobre un elemento y elige Inspect para encontrar qué segmentar. Prefiere los selectores de Selectores recomendados, roles como role="tab" y las variables CSS en lugar de nombres largos de clases de Tailwind. Si una regla no se aplica, revisa el panel Styles en busca de una regla del tema que gane por especificidad o use !important.

Limitaciones

• El CSS se aplica globalmente; usa selectores específicos para evitar conflictos
• Algunos estilos del tema, incluidas las fuentes y el fondo del encabezado de Jam, usan !important o selectores muy específicos, por lo que quizá necesites !important para sobrescribirlos
• En la previsualización local (jamdesk dev), los cambios en tu(s) archivo(s) CSS se aplican al recargar el navegador; en tu sitio publicado, los cambios entran en vigor en el próximo build

¿Qué sigue?