Style et mise en page
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.
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.
.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.
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.
: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
.
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.
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.
: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;
}
It is possible to initialize the Docusaurus theme directly from a docusaurus-theme
query string parameter.
Exemples :
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.
.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
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 :
- Install
docusaurus-plugin-sass
:
- npm
- Yarn
- pnpm
npm install --save docusaurus-plugin-sass sass
yarn add docusaurus-plugin-sass sass
pnpm add docusaurus-plugin-sass sass
- Include the plugin in your
docusaurus.config.js
file:
module.exports = {
// ...
plugins: ['docusaurus-plugin-sass'],
// ...
};
- É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:
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.
.main {
padding: 12px;
article {
color: #ccc;
}
}
import styles from './styles.module.scss';
function MyComponent() {
return (
<main className={styles.main}>
<article>Lorem Ipsum</article>
</main>
);
}