Aller au contenu principal
Version: 3.0.0-rc.1

Configuration du thème

This configuration applies to all main themes.

Common​

Color mode​

Le thème classic fournit par défaut la prise en charge du mode clair et sombre, avec un commutateur dans la barre de navigation pour l'utilisateur.

It is possible to customize the color mode support within the colorMode object.

Champs acceptés :

NomTypePar défautDescription
defaultMode'light' | 'dark''light'Le mode de couleur lorsque l'utilisateur visite le site pour la première fois.
disableSwitchbooleanfalseMasque l'interrupteur dans la barre de navigation. Utile si vous voulez prendre en charge un mode de couleur unique.
respectPrefersColorSchemebooleanfalseWhether to use the prefers-color-scheme media-query, using user system preferences, instead of the hardcoded defaultMode.

Exemple de configuration :

docusaurus.config.js
export default {
  themeConfig: {
    colorMode: {
      defaultMode: 'light',
      disableSwitch: false,
      respectPrefersColorScheme: false,
    },
  },
};
attention

With respectPrefersColorScheme: true, the defaultMode is overridden by user system preferences.

Si vous ne voulez prendre en charge qu'un seul mode couleur, vous devriez ignorer les préférences du système utilisateur.

Meta image​

You can configure a default image that will be used for your meta tag, in particular og:image and twitter:image.

Champs acceptés :

NomTypePar défautDescription
imagestringundefinedL'URL de la méta image pour le site. Par rapport au répertoire "static" de votre site. Ne peuvent pas être des SVG. Peut également être des URL externes.

Exemple de configuration :

docusaurus.config.js
export default {
  themeConfig: {
    image: 'img/docusaurus.png',
  },
};

Metadata​

Vous pouvez configurer des métadonnées HTML supplémentaires (et remplacer celles existantes).

Champs acceptés :

NomTypePar défautDescription
metadataMetadata[][]Any field will be directly passed to the <meta /> tag. Possible fields include id, name, property, content, itemprop, etc.

Exemple de configuration :

docusaurus.config.js
export default {
  themeConfig: {
    metadata: [{name: 'twitter:card', content: 'summary'}],
  },
};

Announcement bar​

Parfois, vous voulez annoncer quelque chose dans votre site Web. Juste pour ce cas, vous pouvez ajouter une barre d'annonce. Il s'agit d'un panneau non fixe et éventuellement dissimulable au-dessus de la barre de navigation. All configuration are in the announcementBar object.

Champs acceptés :

NomTypePar défautDescription
idstring'announcement-bar'Toute valeur qui identifiera ce message.
contentstring''Le contenu de l'annonce. Le HTML sera interpolé.
backgroundColorstring'#fff'Couleur en arrière plan de toute la barre.
textColorstring'#000'Couleur du texte de l'annonce.
isCloseablebooleantrueSi cette annonce peut être ignorée avec un bouton '×'.

Exemple de configuration :

docusaurus.config.js
export default {
  themeConfig: {
    announcementBar: {
      id: 'support_us',
      content:
        'We are looking to revamp our docs, please fill <a target="_blank" rel="noopener noreferrer" href="#">this survey</a>',
      backgroundColor: '#fafbfc',
      textColor: '#091E42',
      isCloseable: false,
    },
  },
};

Champs acceptés :

NomTypePar défautDescription

The logo can be placed in static folder. L'URL du logo est défini par défaut sur l'URL de base de votre site. Bien que vous puissiez spécifier votre propre URL pour le logo, s'il s'agit d'un lien externe, il s'ouvrira dans un nouvel onglet. De plus, vous pouvez remplacer une valeur pour l'attribut cible du lien du logo, ce qui peut s'avérer pratique si vous hébergez les docs du site Web dans un sous-répertoire de votre site Web principal, et dans ce cas, vous n'avez probablement pas besoin d'un lien dans le logo vers le site Web principal qui s'ouvrira dans un nouvel onglet.

Pour améliorer la prise en charge du mode sombre, vous pouvez également définir un logo différent pour ce mode.

Champs acceptés :

NomTypePar défautDescription

Exemple de configuration :

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      title: 'Site Title',
      logo: {
        alt: 'Site Logo',
        src: 'img/logo.svg',
        srcDark: 'img/logo_dark.svg',
        href: 'https://docusaurus.io/',
        target: '_self',
        width: 32,
        height: 32,
        className: 'custom-navbar-logo-class',
        style: {border: 'solid red'},
      },
    },
  },
};

You can add items to the navbar via themeConfig.navbar.items.

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'doc',
          position: 'left',
          docId: 'introduction',
          label: 'Docs',
        },
        {to: 'blog', label: 'Blog', position: 'left'},
        {
          type: 'docsVersionDropdown',
          position: 'right',
        },
        {
          type: 'localeDropdown',
          position: 'right',
        },
        {
          href: 'https://github.com/facebook/docusaurus',
          position: 'right',
          className: 'header-github-link',
          'aria-label': 'GitHub repository',
        },
      ],
    },
  },
};

The items can have different behaviors based on the type field. Les sections ci-dessous vous présenteront tous les types d'éléments de la barre de navigation disponibles.

Par défaut, les éléments de la barre de navigation sont des liens ordinaires (internes ou externes).

React Router should automatically apply active link styling to links, but you can use activeBasePath in edge cases. For cases in which a link should be active on several different paths (such as when you have multiple doc folders under the same sidebar), you can use activeBaseRegex. activeBaseRegex is a more flexible alternative to activeBasePath and takes precedence over it -- Docusaurus parses it into a regular expression that is tested against the current URL.

Outbound (external) links automatically get target="_blank" rel="noopener noreferrer" attributes.

Champs acceptés :

NomTypePar défautDescription
remarque

En plus des champs ci-dessus, vous pouvez spécifier d'autres attributs arbitraires qui peuvent être appliqués à un lien HTML.

Exemple de configuration :

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          to: 'docs/introduction',
          // Only one of "to" or "href" should be used
          // href: 'https://www.facebook.com',
          label: 'Introduction',
          // Only one of "label" or "html" should be used
          // html: '<b>Introduction</b>'
          position: 'left',
          activeBaseRegex: 'docs/(next|v8)',
          target: '_blank',
        },
      ],
    },
  },
};

Navbar items of the type dropdown has the additional items field, an inner array of navbar items.

Navbar dropdown items only accept the following "link-like" item types:

Note that the dropdown base item is a clickable link as well, so this item can receive any of the props of a plain navbar link.

Champs acceptés :

NomTypePar défautDescription

Exemple de configuration :

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'dropdown',
          label: 'Community',
          position: 'left',
          items: [
            {
              label: 'Facebook',
              href: 'https://www.facebook.com',
            },
            {
              type: 'doc',
              label: 'Social',
              docId: 'social',
            },
            // ... plus d'éléments
          ],
        },
      ],
    },
  },
};

If you want to link to a specific doc, this special navbar item type will render the link to the doc of the provided docId. It will get the class navbar__link--active as long as you browse a doc of the same sidebar.

Champs acceptés :

NomTypePar défautDescription

Exemple de configuration :

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'doc',
          position: 'left',
          docId: 'introduction',
          label: 'Docs',
        },
      ],
    },
  },
};

Vous pouvez lier un élément de la barre de navigation au premier lien du document (qui peut être un lien de doc ou un index de catégorie généré) d'une barre latérale donnée sans avoir à coder en dur un ID de documentation.

Champs acceptés :

NomTypePar défautDescription
astuce

Utilisez ce type d'élément de la barre de navigation si votre barre latérale est mise à jour souvent et que l'ordre n'est pas stable.

Exemple de configuration :

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'docSidebar',
          position: 'left',
          sidebarId: 'api',
          label: 'API',
        },
      ],
    },
  },
};
sidebars.js
export default {
  tutorial: [
    {
      type: 'autogenerated',
      dirName: 'guides',
    },
  ],
  api: [
    'cli', // L'élément de la barre de navigation renvoie à ce doc
    'docusaurus-core',
    {
      type: 'autogenerated',
      dirName: 'api',
    },
  ],
};

Si vous utilisez des docs avec la gestion des versions, ce type spécial d'élément de la barre de navigation affichera un menu déroulant avec toutes les versions disponibles de votre site.

L'utilisateur sera en mesure de passer d'une version à une autre, tout en restant sur le même doc (tant que l'ID du doc est constant entre les versions).

Champs acceptés :

NomTypePar défautDescription

Exemple de configuration :

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'docsVersionDropdown',
          position: 'left',
          dropdownItemsAfter: [{to: '/versions', label: 'Toutes les versions'}],
          dropdownActiveClassDisabled: true,
        },
      ],
    },
  },
};

Si vous utilisez des docs avec la gestion de version, ce type spécial d'élément de la barre de navigation sera lié à la version active/consultée de votre doc (dépend de l'URL actuelle), et sinon se placera sur la dernière version.

Champs acceptés :

NomTypePar défautDescription

Exemple de configuration :

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'docsVersion',
          position: 'left',
          to: '/path',
          label: 'label',
        },
      ],
    },
  },
};

If you use the i18n feature, this special navbar item type will render a dropdown with all your site's available locales.

L'utilisateur pourra basculer d'une locale à une autre, tout en restant sur la même page.

Champs acceptés :

NomTypePar défautDescription

Exemple de configuration :

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'localeDropdown',
          position: 'left',
          dropdownItemsAfter: [
            {
              to: 'https://my-site.com/help-us-translate',
              label: 'Aidez-nous à traduire',
            },
          ],
        },
      ],
    },
  },
};

If you use the search, the search bar will be the rightmost element in the navbar.

Cependant, avec ce type spécial d'élément de la barre de navigation, vous pouvez changer l'emplacement par défaut.

NomTypePar défautDescription
docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'search',
          position: 'right',
        },
      ],
    },
  },
};

Vous pouvez également rendre votre propre balisage HTML à l'intérieur d'un élément de barre de navigation en utilisant ce type d'élément de barre de navigation.

NomTypePar défautDescription
docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'html',
          position: 'right',
          value: '<button>Give feedback</button>',
        },
      ],
    },
  },
};

Auto-hide sticky navbar​

Vous pouvez activer cette fonctionnalité d'interface utilisateur qui masque automatiquement la barre de navigation lorsqu'un utilisateur commence à faire défiler la page vers le bas, et la réaffiche lorsqu'il la fait défiler vers le haut.

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      hideOnScroll: true,
    },
  },
};

Vous pouvez définir le style statique de la barre de navigation sans désactiver la possibilité de changer de thème. Le style sélectionné s'appliquera toujours quel que soit le thème sélectionné par l'utilisateur.

Currently, there are two possible style options: dark and primary (based on the --ifm-color-primary color). You can see the styles preview in the Infima documentation.

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      style: 'primary',
    },
  },
};

CodeBlock​

Docusaurus uses Prism React Renderer to highlight code blocks. All configuration are in the prism object.

Champs acceptés :

NomTypePar défautDescription
themePrismThemepalenightLe thème Prism à utiliser pour les blocs de code de thème clair.
darkThemePrismThemepalenightLe thème Prism à utiliser pour les blocs de code de thème sombre.
defaultLanguagestringundefinedLe langage par défaut à utiliser pour les blocs de code ne déclarant pas de langage explicite.
magicCommentsMagicCommentConfig[]see belowThe list of magic comments.
type MagicCommentConfig = {
  className: string;
  line?: string;
  block?: {start: string; end: string};
};
const defaultMagicComments = [
  {
    className: 'theme-code-block-highlighted-line',
    line: 'highlight-next-line',
    block: {start: 'highlight-start', end: 'highlight-end'},
  },
];

Theme​

By default, we use Palenight as syntax highlighting theme. You can specify a custom theme from the list of available themes. Vous pouvez également utiliser un thème de coloration syntaxique différent lorsque le site est en mode sombre.

Exemple de configuration :

docusaurus.config.js
import {themes as prismThemes} from 'prism-react-renderer';

export default {
  themeConfig: {
    prism: {
      theme: prismThemes.github,
      darkTheme: prismThemes.dracula,
    },
  },
};
remarque

Si vous utilisez la coloration de ligne de la syntaxe Markdown, vous devrez peut-être spécifier une couleur d'arrière-plan différente pour le thème de coloration syntaxique en mode sombre. Refer to the docs for guidance.

Default language​

Vous pouvez définir un langage par défaut pour les blocs de code si aucun langage n'est ajouté après le triple backticks (c'est-à-dire ```). Note that a valid language name must be passed.

Exemple de configuration :

docusaurus.config.js
export default {
  themeConfig: {
    prism: {
      defaultLanguage: 'javascript',
    },
  },
};

You can add logo and a copyright to the footer via themeConfig.footer. Logo can be placed in static folder. L'URL du logo fonctionne de la même manière que le logo de la barre de navigation.

Champs acceptés :

NomTypePar défautDescription

Exemple de configuration :

docusaurus.config.js
export default {
  themeConfig: {
    footer: {
      logo: {
        alt: 'Meta Open Source Logo',
        src: 'img/meta_oss_logo.png',
        href: 'https://opensource.fb.com',
        width: 160,
        height: 51,
      },
      copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
    },
  },
};

You can add links to the footer via themeConfig.footer.links. There are two types of footer configurations: multi-column footers and simple footers.

Multi-column footer links have a title and a list of FooterItems for each column.

NomTypePar défautDescription

Accepted fields of each FooterItem:

NomTypePar défautDescription

Exemple de configuration multi-colonnes :

docusaurus.config.js
export default {
  footer: {
    links: [
      {
        title: 'Docs',
        items: [
          {
            label: 'Style Guide',
            to: 'docs/',
          },
          {
            label: 'Second Doc',
            to: 'docs/doc2/',
          },
        ],
      },
      {
        title: 'Community',
        items: [
          {
            label: 'Stack Overflow',
            href: 'https://stackoverflow.com/questions/tagged/docusaurus',
          },
          {
            label: 'Discord',
            href: 'https://discordapp.com/invite/docusaurus',
          },
          {
            label: 'Twitter',
            href: 'https://twitter.com/docusaurus',
          },
          {
            html: `
                <a href="https://www.netlify.com" target="_blank" rel="noreferrer noopener" aria-label="Deploys by Netlify">
                  <img src="https://www.netlify.com/img/global/badges/netlify-color-accent.svg" alt="Deploys by Netlify" width="114" height="51" />
                </a>
              `,
          },
        ],
      },
    ],
  },
};

A simple footer just has a list of FooterItems displayed in a row.

Exemple de configuration simple :

docusaurus.config.js
export default {
  footer: {
    links: [
      {
        label: 'Stack Overflow',
        href: 'https://stackoverflow.com/questions/tagged/docusaurus',
      },
      {
        label: 'Discord',
        href: 'https://discordapp.com/invite/docusaurus',
      },
      {
        label: 'Twitter',
        href: 'https://twitter.com/docusaurus',
      },
      {
        html: `
            <a href="https://www.netlify.com" target="_blank" rel="noreferrer noopener" aria-label="Deploys by Netlify">
              <img src="https://www.netlify.com/img/global/badges/netlify-color-accent.svg" alt="Deploys by Netlify" width="114" height="51" />
            </a>
          `,
      },
    ],
  },
};

Table of Contents​

You can adjust the default table of contents via themeConfig.tableOfContents.

NomTypePar défautDescription
minHeadingLevelnumber2Le niveau de titre minimum affiché dans la table des matières. Doit être compris entre 2 et 6 et inférieur ou égal à la valeur maximale.
maxHeadingLevelnumber3Niveau maximum affiché dans la table des matières. Doit être un entier entre 2 et 6.

Exemple de configuration :

docusaurus.config.js
export default {
  themeConfig: {
    tableOfContents: {
      minHeadingLevel: 2,
      maxHeadingLevel: 5,
    },
  },
};

Hooks​

useColorMode​

Un hook React pour accéder au contexte de couleur. Ce contexte contient des fonctions permettant de définir le mode clair et le mode sombre et expose une variable booléenne, indiquant le mode actuellement utilisé.

Exemple d'utilisation :

import React from 'react';
import {useColorMode} from '@docusaurus/theme-common';

const Example = () => {
  const {colorMode, setColorMode} = useColorMode();

  return <h1>Dark mode is now {colorMode === 'dark' ? 'on' : 'off'}</h1>;
};
remarque

The component calling useColorMode must be a child of the Layout component.

function ExamplePage() {
  return (
    <Layout>
      <Example />
    </Layout>
  );
}

i18n​

Read the i18n introduction first.

Translation files location​

  • Base path: website/i18n/[locale]/docusaurus-theme-[themeName]
  • Multi-instance path: N/A
  • JSON files: extracted with docusaurus write-translations
  • Markdown files: N/A

Example file-system structure​

website/i18n/[locale]/docusaurus-theme-classic
│
│ # traductions pour le thème
├── navbar.json
└── footer.json