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. 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 valeurs arbitraires de Tailwind CSS ne sont pas prises en charge. Pour des valeurs personnalisées, utilisez plutôt la prop style.

<img style={{ width: '350px', margin: '12px auto' }} src="/path/image.jpg" />

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. 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');

Si votre site utilise l’authentification, les scripts personnalisés peuvent lire l’utilisateur connecté 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é.

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

  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é. Utilisez l’opérateur d’enchaînement optionnel pour lire les champs imbriqués.