Style et mise en page

astuce

Cette section est axée sur le style à travers les feuilles de style. For more advanced customizations (DOM structure, React code...), refer to the swizzling guide.

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.

Global styles

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.

If you're using @docusaurus/preset-classic, you can create your own CSS files (e.g. /src/css/custom.css) and import them globally by passing them as an option of the classic theme.

docusaurus.config.js

module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        theme: {
          customCss: [require.resolve('./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">Purple Heading!</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 :

• Theme class names. These class names are listed exhaustively in the next subsection. Ils n'ont aucune propriété par défaut. Vous devez toujours cibler en priorité ces noms de classe stables dans votre CSS personnalisé.
• Infima class names. These class names are found in the classic theme and usually follow the BEM convention of 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. However, you can modify Infima CSS variables.
• CSS module class names. These class names have a hash in production (codeBlockContainer_RIuc) and are appended with a long file path in development. 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é. If you must, you can use an attribute selector ([class*='codeBlockContainer']) that ignores the hash.

Theme Class Names

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

If you can't find a way to create a robust CSS selector, please report your customization use-case and we will consider adding new class names.

Exhaustive list of stable class names

export const ThemeClassNames = {
  page: {
    blogListPage: 'blog-list-page',
    blogPostPage: 'blog-post-page',
    blogTagsListPage: 'blog-tags-list-page',
    blogTagPostListPage: 'blog-tags-post-list-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',
    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: {
  },
} as const;

Styling your site with Infima

@docusaurus/preset-classic uses Infima as the underlying styling framework. 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). For more details, check out the Infima website.

When you scaffold your Docusaurus project with create-docusaurus, the website will be generated with basic Infima stylesheets and default styling. 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. We recommend using ColorBox to find the different shades of colors for your chosen primary color.

Alternatively, use the following tool to generate the different shades for your website and copy the variables into /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;
}

Dark Mode

In light mode, the <html> element has a data-theme="light" attribute; in dark mode, it's data-theme="dark". Therefore, you can scope your CSS to dark-mode-only by targeting html with a specific attribute.

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

It is possible to initialize the Docusaurus theme directly from a docusaurus-theme query string parameter.

Exemples :

• https://docusaurus.io/?docusaurus-theme=dark
• https://docusaurus.io/docs/configuration?docusaurus-theme=light

Mobile View

Docusaurus uses 996px as the cutoff between mobile screen width and desktop. 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;
  }
}

CSS modules

To style your components using CSS Modules, name your stylesheet files with the .module.css suffix (e.g. 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). This is similar to the convention used in 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. Welcoming PRs.

Sass/SCSS

To use Sass/SCSS as your CSS preprocessor, install the unofficial Docusaurus 2 plugin docusaurus-plugin-sass. Ce plugin fonctionne aussi bien pour les styles globaux que pour l'approche des modules CSS :

1. Install 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. Include the plugin in your docusaurus.config.js file:

docusaurus.config.js

module.exports = {
  // ...
  plugins: ['docusaurus-plugin-sass'],
  // ...
};

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

Global styles using Sass/SCSS

You can now set the customCss property of @docusaurus/preset-classic to point to your Sass/SCSS file:

docusaurus.config.js

module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        // ...
        theme: {
          customCss: [require.resolve('./src/css/custom.scss')],
        },
        // ...
      },
    ],
  ],
};

Modules using Sass/SCSS

Name your stylesheet files with the .module.scss suffix (e.g. welcome.module.scss) instead of .css. Webpack will use sass-loader to preprocess your stylesheets and load them as CSS modules.

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