Scripts personalizados

Usa CSS para dar estilo a los elementos HTML o agrega CSS y JavaScript personalizados para adaptar por completo el aspecto y la experiencia de tu documentación.

Usa Tailwind CSS v3 para dar estilo a elementos HTML y componentes. Puedes controlar el diseño, el espaciado, los colores y otras propiedades visuales. Algunas clases comunes son:

• w-full - Ancho completo
• aspect-video - Relación de aspecto 16:9
• rounded-xl - Esquinas redondeadas grandes
• block, hidden - Control de visualización
• dark:hidden, dark:block - Visibilidad en modo oscuro

Los componentes aceptan una prop className. Mintlify combina tus clases con los estilos propios del componente, por lo que puedes cambiar el estilo de una sola instancia sin envolverla en marcado adicional ni escribir una regla CSS que lo anule.

<Note className="mt-0">This callout has no top margin.</Note>

<Card title="Quickstart" href="/quickstart" className="border-2 border-blue-500">
  Deploy your first documentation site.
</Card>

Tres componentes no aceptan className: Banner, MDX y Visibility.

Usa valores arbitrarios cuando ninguna clase utilitaria cubra el valor que necesitas.

<img src="/images/diagram.png" alt="System architecture diagram" className="w-[450px]" />

<Frame className="lg:w-[calc(100%-2rem)] bg-[#0f172a]">
  <img src="/images/hero.png" alt="Product hero image" />
</Frame>

Las variantes funcionan como en cualquier proyecto de Tailwind, incluidos los prefijos responsivos (sm:, md:, lg:), las variantes de estado (hover:, focus:), dark:, las variantes de atributos de datos (data-[state=open]:), los modificadores de opacidad (bg-black/50) y el modificador de importancia !.

Mintlify genera CSS para las clases de Tailwind que encuentra en el código fuente de tu página, así que escribe los nombres de clase completos.

{/* Generates CSS: the full class name appears in the page source. */}
<div className="bg-blue-500" />

{/* Generates no CSS: the class name is assembled at runtime. */}
<div className={`bg-${color}-500`} />

Mintlify incluye automáticamente cualquier archivo .css dentro de tu directorio de contenido en todas las páginas de tu sitio de documentación, del mismo modo que incluye los archivos .js personalizados. El directorio de contenido es la carpeta de tu repositorio que contiene tu archivo docs.json y tus páginas MDX. No necesitas importar ni referenciar el archivo desde docs.json ni desde tus archivos MDX.

Para añadir estilos personalizados, crea un archivo .css (por ejemplo, style.css) en cualquier nivel de tu directorio de contenido. Cualquier nombre de clase, selector de ID o selector de elemento que definas quedará disponible en todos tus archivos MDX.

Por ejemplo, define una clase en style.css:

.my-callout {
  border-radius: 1rem;
  background: #f0f9ff;
  padding: 1rem;
}

Luego úsala en cualquier archivo MDX con la prop className:

<div className="my-callout">
  Contenido aquí.
</div>

Puedes combinar nombres de clase personalizados con clases de Tailwind CSS en el mismo elemento.

El CSS personalizado se aplica a todas las páginas de tu sitio, incluidas las páginas en modo personalizado y las páginas de aterrizaje. Para limitar los estilos a una página o sección específica, usa el selector de atributo html[data-current-path="..."] descrito en Atributos de datos.

Las referencias y el estilo de los elementos comunes están sujetos a cambios. Usa estilos personalizados con precaución, ya que pueden producirse cambios incompatibles en futuras actualizaciones.

Por ejemplo, puedes agregar el siguiente archivo style.css para personalizar los estilos de la barra de navegación y el pie de página.

#navbar {
  background: #fffff2;
  padding: 1rem;
}

footer {
  margin-top: 2rem;
}

Mintlify expone dos tipos de hooks CSS para segmentación:

• Selectores de ID: elementos únicos a nivel de página que se apuntan con #value { } en CSS
• Selectores de elemento: elementos de componente y diseño que se apuntan con value { } en CSS (sin prefijo # o .)

Cada ID aparece una vez por página. Úsalos como #value en CSS. Por ejemplo, #navbar { background: red; }.

Pueden aparecer múltiples instancias de estos elementos en una página. Úsalos como value en CSS. Por ejemplo, accordion { border: 1px solid red; }.

El JavaScript personalizado te permite agregar código ejecutable a nivel global. Es equivalente a insertar una etiqueta <script> con código JS en cada página.

Mintlify incluye cualquier archivo .js dentro de tu directorio de contenido en cada página de tu sitio de documentación, incluidas las páginas en modo personalizado y las páginas de aterrizaje. Los archivos JavaScript personalizados se ejecutan después de que la página se vuelve interactiva. No puedes limitarlos a páginas específicas y, cuando hay varios archivos .js presentes, todos se ejecutan sin un orden garantizado.

Para cargar un script de terceros, inyecta un elemento <script> desde tu archivo JavaScript personalizado en lugar de agregar etiquetas <script src="..."> directamente en MDX:

const script = document.createElement('script');
script.src = 'https://example.com/widget.js';
script.async = true;
document.head.appendChild(script);

Por ejemplo, puedes agregar el archivo ga.js siguiente para habilitar Google Analytics en toda la documentación.

window.dataLayer = window.dataLayer || [];
function gtag() {
  dataLayer.push(arguments);
}
gtag('js', new Date());

gtag('config', 'TAG_ID');

Usa window.mintlify.api.playground.setServerVariables para rellenar previamente las variables de servidor de OpenAPI desde JavaScript personalizado. Úsalo cuando los valores estén disponibles después de cargar la página, por ejemplo, al inicializarse un SDK de autenticación o cambiar un inquilino. El método actualiza los API Playgrounds abiertos y se aplica a los que abras después.

Pasa un objeto con valores de tipo string. Cada llamada reemplaza por completo la sobreescritura en tiempo de ejecución. Las claves omitidas se eliminan y los valores no válidos se ignoran. Los valores en tiempo de ejecución tienen prioridad sobre los valores predeterminados de OpenAPI y las variables de servidor guardadas.

window.mintlify.api.playground.setServerVariables({
  tenantDomain: 'example.us.auth0.com',
});

Llama a window.mintlify.api.playground.clearServerVariables() cuando los valores ya no se apliquen, por ejemplo, después de cerrar sesión. Después de borrarlos, el API Playground vuelve a sus otros valores configurados.

window.mintlify.api.playground.clearServerVariables();

Las llamadas realizadas antes de que se inicialice el cliente se ponen en cola y se aplican cuando se inicializa. La sobreescritura se mantiene en memoria durante la sesión de la página. No escribe en localStorage ni en el almacenamiento de credenciales. Una actualización completa de la página la elimina.

Si tu sitio utiliza autenticación o personalización, los scripts personalizados pueden leer el visitante identificado desde window.mintlify.user. Es el mismo objeto que se expone en las páginas MDX como la variable user, por lo que refleja el campo content de tus datos de usuario.

Como los scripts personalizados se ejecutan antes de que la información del usuario se resuelva, escucha el evento mintlify:user para reaccionar en cuanto el objeto de usuario esté disponible. El evento se dispara cuando la información del usuario se resuelve y también cada vez que cambia. Su detail es el objeto de usuario, o null cuando el visitante ha cerrado sesión o no está identificado.

window.addEventListener('mintlify:user', (event) => {
  const user = event.detail;
  if (!user) return; // Signed out or unidentified.

  renderAppLauncher(user);
});

Si el usuario ya se ha resuelto cuando se ejecuta tu script, lee window.mintlify.user directamente.

const user = window.mintlify?.user;
if (user) {
  renderAppLauncher(user);
}

window.mintlify.user es undefined hasta que la información del usuario se resuelva y también cuando el visitante ha cerrado sesión o no está identificado. Utiliza el encadenamiento opcional al leer campos anidados.