Version: 2.0.0-beta.3

Style et mise en page

CSS traditionnel#

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 dans le preset.

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. Il s'agit de l'approche la plus traditionnelle de l'écriture des feuilles de style CSS. Elle convient parfaitement aux petits sites Web qui ne sont pas très personnalisés.

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 exécutez init votre projet Docusaurus 2, le site web sera généré avec des feuilles de style Infima de base et un style par défaut. Vous pouvez personnaliser le style en modifiant le fichier /src/css/custom.css.

/src/css/custom.css

/** * Vous pouvez remplacer les variables Infima par défaut ici. * Remarque : ce n'est pas une liste complète des variables --ifm- . */:root {  --ifm-color-primary: #25c2a0;  --ifm-color-primary-dark: rgb(33, 175, 144);  --ifm-color-primary-darker: rgb(31, 165, 136);  --ifm-color-primary-darkest: rgb(26, 136, 112);  --ifm-color-primary-light: rgb(70, 203, 174);  --ifm-color-primary-lighter: rgb(102, 212, 189);  --ifm-color-primary-lightest: rgb(146, 224, 208);  --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.

Primary Color:

CSS Variable Name	Hex	Adjustment
`--ifm-color-primary-lightest`	`#80aaef`
`--ifm-color-primary-lighter`	`#5a91ea`
`--ifm-color-primary-light`	`#4e89e8`
`--ifm-color-primary`	`#3578e5`	0
`--ifm-color-primary-dark`	`#1d68e1`
`--ifm-color-primary-darker`	`#1b62d4`
`--ifm-color-primary-darkest`	`#1751af`

Replace the variables in src/css/custom.css with these new variables.

--ifm-color-primary: #3578e5;--ifm-color-primary-dark: #1d68e1;--ifm-color-primary-darker: #1b62d4;--ifm-color-primary-darkest: #1751af;--ifm-color-primary-light: #4e89e8;--ifm-color-primary-lighter: #5a91ea;--ifm-color-primary-lightest: #80aaef;

Mode sombre#

Pour personnaliser les variables Infima pour le mode foncé, vous pouvez ajouter ce qui suit à src/css/custom.css.

/src/css/custom.css

html[data-theme='dark'] {  --ifm-color-primary: #4e89e8;  --ifm-color-primary-dark: #5a91ea;  /* toute autre couleur que vous souhaitez écraser */}

Approche de style#

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.

En supposant que vous utilisez @docusaurus/preset-classic et que /src/css/custom.css a été transmis à la configuration du preset, les styles contenus dans ce fichier seraient disponibles globalement.

/src/css/custom.css

.purple-text {  color: rebeccapurple;}

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

Noms de classe du thème#

Nous fournissons quelques noms de classes CSS prédéfinis afin de permettre aux développeurs de styliser la mise en page d'une page de manière globale dans Docusaurus. Le but est d'avoir des noms de classe stables partagés par tous les thèmes qui sont censés être ciblés par des CSS personnalisés.

export const ThemeClassNames = {  page: {    blogListPage: 'blog-list-page',    blogPostPage: 'blog-post-page',    blogTagsListPage: 'blog-tags-list-page',    blogTagsPostPage: 'blog-tags-post-page',    docPage: 'doc-page',    mdxPage: 'mdx-page',  },  wrapper: {    main: 'main-wrapper',    blogPages: 'blog-wrapper',    docPages: 'docs-wrapper',    mdxPages: 'mdx-wrapper',  },};

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

caution

Cette section est en cours de rédaction. Les PR sont les bienvenues.

Sass/SCSS#

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

Installez docusaurus-plugin-sass:

npm
Yarn

npm install --save docusaurus-plugin-sass

yarn add docusaurus-plugin-sass

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

docusaurus.config.js

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

É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

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