Style et mise en page

astuce

Cette section est axée sur le style à travers les feuilles de style. Pour des personnalisations plus avancées (structure DOM, code React...), reportez-vous au guide du swizzling.

Un site Docusaurus est une application React mono-page. Vous pouvez la styliser de la même manière que les applications React.

Il y a quelques approches/frameworks qui fonctionneront, selon vos préférences et le type de site que vous essayez de construire. Les sites Web très interactifs et se comportant davantage comme des applications Web bénéficieront d'approches de style plus modernes qui associent les styles aux composants. Le style des composants peut également être particulièrement utile lorsque vous souhaitez personnaliser ou modifier un composant.

Styles globaux

Il s'agit de la méthode de style la plus traditionnelle que la plupart des développeurs (y compris les développeurs non frontaux) connaissent. Il fonctionne très bien pour les petits sites web qui n'ont pas beaucoup de personnalisation.

Si vous utilisez @docusaurus/preset-classic, vous pouvez créer vos propres fichiers CSS (par exemple /src/css/custom.css) et les importer globalement en les passant comme option du thème classic.

docusaurus.config.js

export default {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        theme: {
          customCss: ['./src/css/custom.css'],
        },
      },
    ],
  ],
};

Tout CSS que vous écrivez dans ce fichier sera disponible globalement et pourra être référencé directement à l'aide de littéraux de chaînes de caractères.

/src/css/custom.css

.purple-text {
  color: rebeccapurple;
}

function MyComponent() {
  return (
    <main>
      <h1 className="purple-text">Entête violette !</h1>
    </main>
  );
}

Si vous souhaitez ajouter une feuille de style CSS à un élément, vous pouvez ouvrir le DevTools dans votre navigateur pour inspecter ses noms de classe. Il existe plusieurs types de noms de classe :

• Les noms de la classe du thème. Ces noms de classes sont énumérés de façon exhaustive dans la section suivante. Ils n'ont aucune propriété par défaut. Vous devez toujours cibler en priorité ces noms de classe stables dans votre CSS personnalisé.
• Les noms de la classe Infima. Ces noms de classes sont trouvés dans le thème classic et suivent généralement la convention BEM de block__element--modifier. Elles sont généralement stables mais sont toujours considérées comme des détails d'implémentation, vous devez donc généralement éviter de les cibler. Cependant, vous pouvez modifier les variables CSS de Infima.
• Les noms de classe des modules CSS. These class names end with a hash which may change over time (codeBlockContainer_RIuc). Elles sont considérées comme des détails d'implémentation et vous devriez presque toujours éviter de les cibler dans votre CSS personnalisé. Si vous devez le faire, vous pouvez utiliser un sélecteur d'attribut ([class*='codeBlockContainer']) qui ignore le hash.

Noms de classe du thème

Nous fournissons des noms de classes CSS stables pour un style de mise en page global robuste et facile à maintenir. Ces noms sont des noms de thème et destinés à être ciblés par des CSS personnalisés.

astuce

Si vous ne trouvez pas le moyen de créer un sélecteur CSS robuste, veuillez reporter votre cas d'utilisation de personnalisation et nous envisagerons d'ajouter de nouveaux noms de classe.

Liste exhaustive des noms de classes stables

export const ThemeClassNames = {
  page: {
    blogListPage: 'blog-list-page',
    blogPostPage: 'blog-post-page',
    blogTagsListPage: 'blog-tags-list-page',
    blogTagPostListPage: 'blog-tags-post-list-page',
    blogAuthorsListPage: 'blog-authors-list-page',
    blogAuthorsPostsPage: 'blog-authors-posts-page',
    docsDocPage: 'docs-doc-page',
    docsTagsListPage: 'docs-tags-list-page',
    docsTagDocListPage: 'docs-tags-doc-list-page',
    mdxPage: 'mdx-page',
  },
  wrapper: {
    main: 'main-wrapper',
    blogPages: 'blog-wrapper',
    docsPages: 'docs-wrapper',
    mdxPages: 'mdx-wrapper',
  },
  common: {
    editThisPage: 'theme-edit-this-page',
    lastUpdated: 'theme-last-updated',
    backToTopButton: 'theme-back-to-top-button',
    codeBlock: 'theme-code-block',
    admonition: 'theme-admonition',
    unlistedBanner: 'theme-unlisted-banner',
    draftBanner: 'theme-draft-banner',
    admonitionType: (type: string) => `theme-admonition-${type}`,
  },
  layout: {
  },
  docs: {
    docVersionBanner: 'theme-doc-version-banner',
    docVersionBadge: 'theme-doc-version-badge',
    docBreadcrumbs: 'theme-doc-breadcrumbs',
    docMarkdown: 'theme-doc-markdown',
    docTocMobile: 'theme-doc-toc-mobile',
    docTocDesktop: 'theme-doc-toc-desktop',
    docFooter: 'theme-doc-footer',
    docFooterTagsRow: 'theme-doc-footer-tags-row',
    docFooterEditMetaRow: 'theme-doc-footer-edit-meta-row',
    docSidebarContainer: 'theme-doc-sidebar-container',
    docSidebarMenu: 'theme-doc-sidebar-menu',
    docSidebarItemCategory: 'theme-doc-sidebar-item-category',
    docSidebarItemLink: 'theme-doc-sidebar-item-link',
    docSidebarItemCategoryLevel: (level: number) =>
      `theme-doc-sidebar-item-category-level-${level}` as const,
    docSidebarItemLinkLevel: (level: number) =>
      `theme-doc-sidebar-item-link-level-${level}` as const,
  },
  blog: {
    blogFooterTagsRow: 'theme-blog-footer-tags-row',
    blogFooterEditMetaRow: 'theme-blog-footer-edit-meta-row',
  },
  pages: {
    pageFooterEditMetaRow: 'theme-pages-footer-edit-meta-row',
  },
} as const;

Styliser votre site avec Infima

@docusaurus/preset-classic utilise Infima comme framework de style. Infima offre une mise en page flexible et un style de composants d'interface utilisateur communs adaptés aux sites Web axés sur le contenu (blogs, documentation, pages de présentation). Pour plus de détails, consultez le site Infima.

Lorsque vous échafaudez votre projet Docusaurus avec create-docusaurus, le site web sera généré avec les feuilles de style Infima de base et le style par défaut. Vous pouvez remplacer les variables CSS d'Infima de manière globale.

/src/css/custom.css

:root {
  --ifm-color-primary: #25c2a0;
  --ifm-code-font-size: 95%;
}

Infima utilise 7 nuances de chaque couleur. Nous vous recommandons d'utiliser ColorBox pour trouver les différentes nuances de couleurs pour la couleur principale que vous avez choisie.

Sinon, utilisez l'outil suivant pour générer les différentes nuances pour votre site web et copiez les variables dans /src/css/custom.css.

astuce

Visez au moins Taux de contraste WCAG-AA pour la couleur principale afin de garantir la lisibilité. Utilisez le site Web du Docusaurus lui-même pour avoir un aperçu de votre palette de couleurs. Vous pouvez utiliser d'autres palettes en mode sombre, car une couleur ne fonctionne généralement pas en mode clair et en mode sombre.

Couleur principale :

Arrière-plan :

Nom de la variable CSS	Hex	Ajustement	Taux de contraste
--ifm-color-primary-lightest	#3cad6e		Fail 🔴
--ifm-color-primary-lighter	#359962		Fail 🔴
--ifm-color-primary-light	#33925d		Fail 🔴
--ifm-color-primary	#2e8555	0	AA 👍
--ifm-color-primary-dark	#29784c		AA 👍
--ifm-color-primary-darker	#277148		AA 👍
--ifm-color-primary-darkest	#205d3b		AAA 🏅

Remplacez les variables dans src/css/custom.css par ces nouvelles variables.

/src/css/custom.css

:root {
  --ifm-color-primary: #2e8555;
  --ifm-color-primary-dark: #29784c;
  --ifm-color-primary-darker: #277148;
  --ifm-color-primary-darkest: #205d3b;
  --ifm-color-primary-light: #33925d;
  --ifm-color-primary-lighter: #359962;
  --ifm-color-primary-lightest: #3cad6e;
}

Mode sombre

En mode clair, l'élément <html> a un attribut data-theme="light" et en mode sombre, il a data-theme="dark". Par conséquent, vous pouvez étendre votre CSS au mode sombre uniquement en ciblant html avec un attribut spécifique.

/* Remplace les variables racine Infima */
[data-theme='dark'] {
  --ifm-color-primary: #4e89e8;
}
/* Stylise une classe spécialement en mode sombre */
[data-theme='dark'] .purple-text {
  color: plum;
}

astuce

Il est possible d'initialiser le thème Docusaurus directement à partir d'un paramètre de chaîne de requête docusaurus-theme.

Exemples :

/docs/?docusaurus-theme=dark

/docs/configuration?docusaurus-theme=light

Attributs de données

Il est possible d'injecter des attributs de données <html> avec des paramètres de chaîne de requête suivant le pattern docusaurus-data-<key>. Cela vous permet de styliser différemment une page en fonction de la chaîne de requête.

Par exemple, rendons une de nos pages avec une bordure rouge et aucune barre de navigation :

/src/css/custom.css

html[data-navbar='false'] .navbar {
  display: none;
}

html[data-red-border] div#__docusaurus {
  border: red solid thick;
}

/docs/?docusaurus-data-navbar=false&docusaurus-data-red-border

Mode Iframe

Si vous prévoyez d'intégrer des pages Docusaurus sur un autre site par le biais d'une iframe, il peut être utile de créer un mode d'affichage alternatif et d'utiliser des url iframe tels quehttps://mysite.com/docs/myDoc?docusaurus-data-mode=iframe. Il est de votre responsabilité de fournir les styles supplémentaires et de décider quels éléments de l'interface utilisateur vous voulez conserver ou cacher.

Vue mobile

Docusaurus utilise 996px comme coupure entre la largeur de l'écran mobile et le bureau. Si vous voulez que votre mise en page soit différente dans la vue mobile, vous pouvez utiliser des requêtes multimédia.

.banner {
  padding: 4rem;
}
/** Dans la vue mobile, reduit le padding */
@media screen and (max-width: 996px) {
  .heroBanner {
    padding: 2rem;
  }
}

Personnalisation du breakpoint

Certains composants React, tels que l'entête et la barre latérale, mettent en œuvre une logique JavaScript différente lorsqu'ils sont affichés en mode mobile. Si vous modifiez la valeur du breakpoint dans votre CSS personnalisé, vous voudrez probablement aussi mettre à jour les invocations du hook useWindowSize en swizzlant les composants dans lesquels il est utilisé et en passant un argument d'option explicite.

Modules CSS

Pour styliser vos composants à l'aide de CSS Modules, nommez vos fichiers de feuille de style avec le suffixe .module.css (par exemple welcome.module.css). Webpack chargera ces fichiers CSS en tant que modules CSS et vous devrez faire référence aux noms de classe comme des propriétés du module CSS importé (au lieu d'utiliser des chaînes simples). Ceci est similaire à la convention utilisée dans Create React App.

styles.module.css

.main {
  padding: 12px;
}

.heading {
  font-weight: bold;
}

.contents {
  color: #ccc;
}

import styles from './styles.module.css';

function MyComponent() {
  return (
    <main className={styles.main}>
      <h1 className={styles.heading}>Hello!</h1>
      <article className={styles.contents}>Lorem Ipsum</article>
    </main>
  );
}

Les noms de classe qui seront transformés par webpack en un nom de classe unique au niveau global lors de la construction.

CSS-in-JS

attention

La prise en charge de CSS-in-JS est un travail en cours, si bien que des librairies comme MUI peuvent présenter des bizarreries d'affichage. Les PR sont les bienvenues.

Sass/SCSS

Pour utiliser Sass/SCSS comme votre préprocesseur CSS, installez le plugin non officiel Docusaurus docusaurus-plugin-sass. Ce plugin fonctionne aussi bien pour les styles globaux que pour l'approche des modules CSS :

1. Installez docusaurus-plugin-sass:

npm

npm install --save docusaurus-plugin-sass sass

Yarn

yarn add docusaurus-plugin-sass sass

pnpm

pnpm add docusaurus-plugin-sass sass

2. Ajoutez le plugin dans votre fichier docusaurus.config.js :

docusaurus.config.js

export default {
  // ...
  plugins: ['docusaurus-plugin-sass'],
  // ...
};

3. Écrivez et importez vos feuilles de style en Sass/SCSS comme d'habitude.

Styles globaux utilisant Sass/SCSS

Vous pouvez maintenant définir la propriété customCss de @docusaurus/preset-classic pour pointer vers votre fichier Sass/SCSS :

docusaurus.config.js

export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        // ...
        theme: {
          customCss: ['./src/css/custom.scss'],
        },
        // ...
      },
    ],
  ],
};

Modules utilisant Sass/SCSS

Nommez vos fichiers de feuilles de style avec le suffixe .module.scss (par exemple welcome.module.scss) au lieu de .css. Webpack utilisera sass-loader pour prétraiter vos feuilles de style et les charger en tant que modules CSS.

styles.module.scss

.main {
  padding: 12px;

  article {
    color: #ccc;
  }
}

import styles from './styles.module.scss';

function MyComponent() {
  return (
    <main className={styles.main}>
      <article>Lorem Ipsum</article>
    </main>
  );
}

Prise en charge de TypeScript

Pour activer le support TypeScript pour les modules Sass/SCSS, la configuration TypeScript doit être mise à jour pour ajouter les définitions de type docusaurus-plugin-sass. Cela peut être fait dans le fichier tsconfig.json :

{
  "extends": "@tsconfig/docusaurus/tsconfig.json",
  "compilerOptions": {
    ...
+    "types": ["docusaurus-plugin-sass"]
  }
}