Scripts personnalisés

Utilisez CSS pour mettre en forme les éléments HTML, ou ajoutez du CSS et du JavaScript personnalisés afin d’adapter entièrement l’apparence et l’expérience de votre documentation.

Utilisez Tailwind CSS v3 pour styliser les éléments HTML et les composants. Vous pouvez contrôler la mise en page, l’espacement, les couleurs et d’autres propriétés visuelles. Quelques classes courantes :

• w-full - Pleine largeur
• aspect-video - Ratio 16:9
• rounded-xl - Grandes bordures arrondies
• block, hidden - Contrôle de l’affichage
• dark:hidden, dark:block - Visibilité en mode sombre

Les composants acceptent une prop className. Mintlify fusionne vos classes avec les styles propres du composant, ce qui vous permet de restyliser une seule instance sans l’encapsuler dans du balisage supplémentaire ni écrire une surcharge CSS.

<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>

Trois composants n’acceptent pas className : Banner, MDX et Visibility.

Utilisez des valeurs arbitraires lorsqu’aucune classe utilitaire ne couvre la valeur dont vous avez besoin.

<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>

Les variantes fonctionnent comme dans n’importe quel projet Tailwind, y compris les préfixes responsive (sm:, md:, lg:), les variantes d’état (hover:, focus:), dark:, les variantes d’attributs de données (data-[state=open]:), les modificateurs d’opacité (bg-black/50) et le modificateur d’importance !.

Mintlify génère le CSS des classes Tailwind qu’il trouve dans la source de vos pages ; écrivez donc les noms de classes en toutes lettres.

{/* 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 inclut automatiquement tout fichier .css présent dans votre répertoire de contenu sur chaque page de votre site de documentation, de la même manière qu’il inclut les fichiers .js personnalisés. Le répertoire de contenu est le dossier de votre dépôt qui contient votre fichier docs.json et vos pages MDX. Vous n’avez pas besoin d’importer ni de référencer le fichier depuis docs.json ou depuis vos fichiers MDX.

Pour ajouter des styles personnalisés, créez un fichier .css (par exemple, style.css) à n’importe quel niveau de votre répertoire de contenu. Tous les noms de classes, sélecteurs d’ID ou sélecteurs d’éléments que vous y définissez deviennent disponibles dans tous vos fichiers MDX.

Par exemple, définissez une classe dans style.css :

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

Puis utilisez-la dans n’importe quel fichier MDX avec la prop className :

<div className="my-callout">
  Contenu ici.
</div>

Vous pouvez combiner des noms de classes personnalisés avec les classes Tailwind CSS sur le même élément.

Le CSS personnalisé s’applique à chaque page de votre site, y compris les pages en mode personnalisé et les pages d’accueil. Pour limiter les styles à une page ou une section spécifique, utilisez le sélecteur d’attribut html[data-current-path="..."] décrit dans Attributs de données.

Les références et la mise en forme des éléments courants sont susceptibles de changer. Utilisez les styles personnalisés avec prudence, car des changements incompatibles peuvent survenir lors de futures mises à jour.

Par exemple, vous pouvez ajouter le fichier style.css suivant pour personnaliser la barre de navigation et le pied de page.

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

footer {
  margin-top: 2rem;
}

Mintlify expose deux types de hooks CSS pour le ciblage :

• Sélecteurs d’ID : éléments uniques au niveau de la page ciblés avec #value { } en CSS
• Sélecteurs d’éléments : composants et éléments de mise en page ciblés avec value { } en CSS (sans préfixe # ou .)

Chaque ID apparaît une seule fois par page. Utilisez-les comme #value en CSS. Par exemple, #navbar { background: red; }.

Plusieurs instances de ces éléments peuvent apparaître sur une page. Utilisez-les comme value en CSS. Par exemple, accordion { border: 1px solid red; }.

Le JavaScript personnalisé vous permet d’ajouter du code exécutable personnalisé à l’échelle du site. C’est l’équivalent d’ajouter une balise <script> contenant du code JS sur chaque page.

Mintlify inclut tout fichier .js situé dans le répertoire de contenu de votre documentation dans chaque page de votre site de documentation, y compris les pages en mode personnalisé et les pages d’accueil. Les fichiers JavaScript personnalisés s’exécutent une fois que la page devient interactive. Vous ne pouvez pas les limiter à des pages spécifiques, et lorsque plusieurs fichiers .js sont présents, ils s’exécutent tous sans ordre garanti.

Pour charger un script tiers, injectez un élément <script> depuis votre fichier JavaScript personnalisé plutôt que d’ajouter des balises <script src="..."> brutes en MDX :

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

Par exemple, vous pouvez ajouter le fichier ga.js suivant pour activer Google Analytics sur l’ensemble de la documentation.

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

gtag('config', 'TAG_ID');

Utilisez window.mintlify.api.playground.setServerVariables pour préremplir les variables de serveur OpenAPI depuis votre JavaScript personnalisé. Utilisez-la lorsque les valeurs deviennent disponibles après le chargement de la page, par exemple après l’initialisation d’un SDK d’authentification ou un changement de locataire. La méthode met à jour les API Playgrounds ouverts et s’applique aux prochains Playgrounds.

Transmettez un objet dont les valeurs sont des chaînes. Chaque appel remplace entièrement la surcharge d’exécution. Les clés omises sont supprimées et les valeurs non valides sont ignorées. Les valeurs d’exécution sont prioritaires sur les valeurs par défaut OpenAPI et les variables de serveur enregistrées.

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

Appelez window.mintlify.api.playground.clearServerVariables() lorsque ces valeurs ne s’appliquent plus, par exemple après une déconnexion. Après la suppression, l’API Playground revient à ses autres valeurs configurées.

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

Les appels effectués avant l’initialisation du client sont mis en file d’attente, puis appliqués lors de son initialisation. La surcharge reste en mémoire pendant la session de la page. Elle n’écrit ni dans localStorage ni dans le stockage des identifiants. Un rechargement complet de la page la supprime.

Si votre site utilise l’authentification ou la personnalisation, les scripts personnalisés peuvent lire le visiteur identifié depuis window.mintlify.user. Il s’agit du même objet que celui exposé aux pages MDX via la variable user : il reflète le champ content de vos données utilisateur.

Comme les scripts personnalisés s’exécutent avant que les informations de l’utilisateur ne soient résolues, écoutez l’événement mintlify:user pour réagir dès que l’objet utilisateur est disponible. L’événement se déclenche lorsque les informations de l’utilisateur sont résolues, puis à chaque changement. Son detail correspond à l’objet utilisateur, ou à null lorsque le visiteur est déconnecté ou non identifié.

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

  renderAppLauncher(user);
});

Si l’utilisateur a déjà été résolu au moment où votre script s’exécute, lisez window.mintlify.user directement.

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

window.mintlify.user vaut undefined tant que les informations de l’utilisateur ne sont pas résolues, ainsi que lorsque le visiteur est déconnecté ou non identifié. Utilisez l’opérateur d’enchaînement optionnel pour lire les champs imbriqués.