Aller au contenu principal
Version: 3.0.0-rc.1

API client Docusaurus

Docusaurus fournit quelques API sur les clients qui peuvent vous être utiles lors de la construction de votre site.

Components​

<ErrorBoundary />​

This component creates a React error boundary.

Utilisez-le pour envelopper les composants susceptibles de se bloquer, et affichez une solution de repli lorsque cela se produit au lieu de faire planter toute l'application.

import React from 'react';
import ErrorBoundary from '@docusaurus/ErrorBoundary';

const SafeComponent = () => (
  <ErrorBoundary
    fallback={({error, tryAgain}) => (
      <div>
        <p>This component crashed because of error: {error.message}.</p>
        <button onClick={tryAgain}>Try Again!</button>
      </div>
    )}>
    <SomeDangerousComponentThatMayThrow />
  </ErrorBoundary>
);
astuce

To see it in action, click here:

info

Docusaurus utilise ce composant pour détecter les erreurs dans la mise en page du thème, mais aussi dans l'ensemble de l'application.

remarque

Ce composant ne détecte pas les erreurs de construction et protège uniquement contre les erreurs de rendu côté client qui peuvent survenir lors de l'utilisation de composants d'état de React.

Props​

  • fallback: an optional render callback returning a JSX element. It will receive an object with 2 attributes: error, the error that was caught, and tryAgain, a function (() => void) callback to reset the error in the component and try rendering it again. If not present, @theme/Error will be rendered instead. @theme/Error is used for the error boundaries wrapping the site, above the layout.
attention

The fallback prop is a callback, and not a React functional component. Vous ne pouvez pas utiliser les hooks React à l'intérieur de ce callback.

Ce composant React réutilisable gérera toutes les modifications apportées à la tête (« Head ») du document. Il prend des balises HTML simples et affiche des balises HTML simples et est facile à utiliser pour les débutants. It is a wrapper around React Helmet.

Exemple d'utilisation :

import React from 'react';
import Head from '@docusaurus/Head';

const MySEO = () => (
  <Head>
    <meta property="og:description" content="My custom description" />
    <meta charSet="utf-8" />
    <title>My Title</title>
    <link rel="canonical" href="http://mysite.com/example" />
  </Head>
);

Les composants imbriqués ou les derniers remplaceront les utilisations dupliquées :

<Parent>
  <Head>
    <title>My Title</title>
    <meta name="description" content="Helmet application" />
  </Head>
  <Child>
    <Head>
      <title>Nested Title</title>
      <meta name="description" content="Nested component" />
    </Head>
  </Child>
</Parent>

Sorties :

<head>
  <title>Nested Title</title>
  <meta name="description" content="Nested component" />
</head>

Ce composant permet de créer des liens vers des pages internes ainsi qu'une puissante fonctionnalité de performance appelée « préchargement ». Le préchargement est utilisé pour récupérer les ressources à l'avance, de sorte que les ressources soient récupérées au moment où l'utilisateur navigue avec ce composant. We use an IntersectionObserver to fetch a low-priority request when the <Link> is in the viewport and then use an onMouseOver event to trigger a high-priority request when it is likely that a user will navigate to the requested resource.

The component is a wrapper around react-router’s <Link> component that adds useful enhancements specific to Docusaurus. All props are passed through to react-router’s <Link> component.

External links also work, and automatically have these props: target="_blank" rel="noopener noreferrer".

import React from 'react';
import Link from '@docusaurus/Link';

const Page = () => (
  <div>
    <p>
      Check out my <Link to="/blog">blog</Link>!
    </p>
    <p>
      Follow me on <Link to="https://twitter.com/docusaurus">Twitter</Link>!
    </p>
  </div>
);

to: string​

L'emplacement cible vers lequel vous souhaitez naviguer. Example: /docs/introduction.

<Link to="/courses" />
astuce

Prefer this component to vanilla <a> tags because Docusaurus does a lot of optimizations (e.g. broken path detection, prefetching, applying base URL...) if you use <Link>.

<Redirect/>​

Rendering a <Redirect> will navigate to a new location. Le nouvel emplacement remplacera l'emplacement actuel de la pile d'historique comme le font les redirections côté serveur (HTTP 3xx). You can refer to React Router's Redirect documentation for more info on available props.

Exemple d'utilisation :

import React from 'react';
import {Redirect} from '@docusaurus/router';

const Home = () => {
  return <Redirect to="/docs/test" />;
};
remarque

@docusaurus/router implements React Router and supports its features.

<BrowserOnly/>​

The <BrowserOnly> component permits to render React components only in the browser after the React app has hydrated.

astuce

Use it for integrating with code that can't run in Node.js, because the window or document objects are being accessed.

Props​

  • children: render function prop returning browser-only JSX. Ne sera pas exécuté dans Node.js
  • fallback (optional): JSX to render on the server (Node.js) and until React hydration completes.

Example with code​

import BrowserOnly from '@docusaurus/BrowserOnly';

const MyComponent = () => {
  return (
    <BrowserOnly>
      {() => <span>page url = {window.location.href}</span>}
    </BrowserOnly>
  );
};

Example with a library​

import BrowserOnly from '@docusaurus/BrowserOnly';

const MyComponent = (props) => {
  return (
    <BrowserOnly fallback={<div>Loading...</div>}>
      {() => {
        const LibComponent = require('some-lib').LibComponent;
        return <LibComponent {...props} />;
      }}
    </BrowserOnly>
  );
};

<Interpolate/>​

Un composant d'interpolation simple pour le texte contenant des placeholders dynamiques.

Les placeholders seront remplacés par les valeurs dynamiques fournies et les éléments JSX de votre choix (chaînes, liens, éléments stylés...).

Props​

  • children: text containing interpolation placeholders like {placeholderName}
  • values: object containing interpolation placeholder values
import React from 'react';
import Link from '@docusaurus/Link';
import Interpolate from '@docusaurus/Interpolate';

export default function VisitMyWebsiteMessage() {
  return (
    <Interpolate
      values={{
        firstName: 'Sébastien',
        website: (
          <Link to="https://docusaurus.io" className="my-website-class">
            website
          </Link>
        ),
      }}>
      {'Hello, {firstName}! How are you? Take a look at my {website}'}
    </Interpolate>
  );
}

<Translate/>​

When localizing your site, the <Translate/> component will allow providing translation support to React components, such as your homepage. The <Translate> component supports interpolation.

The translation strings will statically extracted from your code with the docusaurus write-translations CLI and a code.json translation file will be created in website/i18n/[locale].

remarque

The <Translate/> props must be hardcoded strings.

Apart from the values prop used for interpolation, it is not possible to use variables, or the static extraction wouldn't work.

Props​

  • children: untranslated string in the default site locale (can contain interpolation placeholders)
  • id: optional value to be used as the key in JSON translation files
  • description: optional text to help the translator
  • values: optional object containing interpolation placeholder values

Example​

src/pages/index.js
import React from 'react';
import Layout from '@theme/Layout';

import Translate from '@docusaurus/Translate';

export default function Home() {
  return (
    <Layout>
      <h1>
        <Translate
          id="homepage.title"
          description="The homepage welcome message">
          Welcome to my website
        </Translate>
      </h1>
      <main>
        <Translate values={{firstName: 'Sébastien'}}>
          {'Welcome, {firstName}! How are you?'}
        </Translate>
      </main>
    </Layout>
  );
}
remarque

You can even omit the children prop and specify a translation string in your code.json file manually after running the docusaurus write-translations CLI command.

<Translate id="homepage.title" />
info

The <Translate> component supports interpolation. You can also implement string pluralization through some custom code and the translate imperative API.

Hooks​

useDocusaurusContext​

Hook de React pour accéder au contexte Docusaurus. The context contains the siteConfig object from docusaurus.config.js and some additional site metadata.

type PluginVersionInformation =
  | {readonly type: 'package'; readonly version?: string}
  | {readonly type: 'project'}
  | {readonly type: 'local'}
  | {readonly type: 'synthetic'};

type SiteMetadata = {
  readonly docusaurusVersion: string;
  readonly siteVersion?: string;
  readonly pluginVersions: Record<string, PluginVersionInformation>;
};

type I18nLocaleConfig = {
  label: string;
  direction: string;
};

type I18n = {
  defaultLocale: string;
  locales: [string, ...string[]];
  currentLocale: string;
  localeConfigs: Record<string, I18nLocaleConfig>;
};

type DocusaurusContext = {
  siteConfig: DocusaurusConfig;
  siteMetadata: SiteMetadata;
  globalData: Record<string, unknown>;
  i18n: I18n;
  codeTranslations: Record<string, string>;
};

Exemple d'utilisation :

import React from 'react';
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';

const MyComponent = () => {
  const {siteConfig, siteMetadata} = useDocusaurusContext();
  return (
    <div>
      <h1>{siteConfig.title}</h1>
      <div>{siteMetadata.siteVersion}</div>
      <div>{siteMetadata.docusaurusVersion}</div>
    </div>
  );
};
remarque

The siteConfig object only contains serializable values (values that are preserved after JSON.stringify()). Les fonctions, les regex, etc. seraient perdus du côté client.

useIsBrowser​

Returns true when the React app has successfully hydrated in the browser.

attention

Use this hook instead of typeof windows !== 'undefined' in React rendering logic.

The first client-side render output (in the browser) must be exactly the same as the server-side render output (Node.js). Not following this rule can lead to unexpected hydration behaviors, as described in The Perils of Rehydration.

Exemple d'utilisation :

import React from 'react';
import useIsBrowser from '@docusaurus/useIsBrowser';

const MyComponent = () => {
  const isBrowser = useIsBrowser();
  return <div>{isBrowser ? 'Client' : 'Server'}</div>;
};

useBaseUrl​

React hook to prepend your site baseUrl to a string.

attention

Don't use it for regular links!

The /baseUrl/ prefix is automatically added to all absolute paths by default:

  • Markdown: [link](/my/path) will link to /baseUrl/my/path
  • React: <Link to="/my/path/">link</Link> will link to /baseUrl/my/path

Options​

type BaseUrlOptions = {
  forcePrependBaseUrl: boolean;
  absolute: boolean;
};

Example usage:​

import React from 'react';
import useBaseUrl from '@docusaurus/useBaseUrl';

const SomeImage = () => {
  const imgSrc = useBaseUrl('/img/myImage.png');
  return <img src={imgSrc} />;
};
astuce

In most cases, you don't need useBaseUrl.

Prefer a require() call for assets:

<img src={require('@site/static/img/myImage.png').default} />

useBaseUrlUtils​

Sometimes useBaseUrl is not good enough. Ce hook retourne des utilitaires supplémentaires liés à l'URL de base de votre site.

  • withBaseUrl: useful if you need to add base URLs to multiple URLs at once.
import React from 'react';
import {useBaseUrlUtils} from '@docusaurus/useBaseUrl';

const Component = () => {
  const urls = ['/a', '/b'];
  const {withBaseUrl} = useBaseUrlUtils();
  const urlsWithBaseUrl = urls.map(withBaseUrl);
  return <div>{/* ... */}</div>;
};

useGlobalData​

Hook de React pour accéder aux données globales de Docusaurus créées par tous les plugins.

Les données globales sont des espaces nommés par le nom du plugin et l'ID du plugin.

info

L'ID du plugin n'est utile que si un plugin est utilisé plusieurs fois sur le même site. Chaque instance de plugin est capable de créer ses propres données globales.

type GlobalData = Record<
  PluginName,
  Record<
    PluginId, // "default" by default
    any // plugin-specific data
  >
>;

Exemple d'utilisation :

import React from 'react';
import useGlobalData from '@docusaurus/useGlobalData';

const MyComponent = () => {
  const globalData = useGlobalData();
  const myPluginData = globalData['my-plugin']['default'];
  return <div>{myPluginData.someAttribute}</div>;
};
astuce

Inspect your site's global data at ./docusaurus/globalData.json

usePluginData​

Accéder aux données globales créées par une instance spécifique du plugin.

C'est le hook le plus pratique pour accéder aux données globales du plugin et devrait être utilisé la plupart du temps.

pluginId is optional if you don't use multi-instance plugins.

function usePluginData(
  pluginName: string,
  pluginId?: string,
  options?: {failfast?: boolean},
);

Exemple d'utilisation :

import React from 'react';
import {usePluginData} from '@docusaurus/useGlobalData';

const MyComponent = () => {
  const myPluginData = usePluginData('my-plugin');
  return <div>{myPluginData.someAttribute}</div>;
};

useAllPluginInstancesData​

Accéder aux données globales créées par un plugin spécifique. Donné un nom de plugin, il retourne les données de toutes les instances de plugins de ce nom, pour chaque id de plugin.

function useAllPluginInstancesData(
  pluginName: string,
  options?: {failfast?: boolean},
);

Exemple d'utilisation :

import React from 'react';
import {useAllPluginInstancesData} from '@docusaurus/useGlobalData';

const MyComponent = () => {
  const allPluginInstancesData = useAllPluginInstancesData('my-plugin');
  const myPluginData = allPluginInstancesData['default'];
  return <div>{myPluginData.someAttribute}</div>;
};

Functions​

interpolate​

The imperative counterpart of the <Interpolate> component.

Signature​

// Simple string interpolation
function interpolate(text: string, values: Record<string, string>): string;

// JSX interpolation
function interpolate(
  text: string,
  values: Record<string, ReactNode>,
): ReactNode;

Example​

import {interpolate} from '@docusaurus/Interpolate';

const message = interpolate('Welcome {firstName}', {firstName: 'Sébastien'});

translate​

The imperative counterpart of the <Translate> component. Also supporting placeholders interpolation.

astuce

Use the imperative API for the rare cases where a component cannot be used, such as:

  • the page title metadata
  • the placeholder props of form inputs
  • the aria-label props for accessibility

Signature​

function translate(
  translation: {message: string; id?: string; description?: string},
  values: Record<string, string>,
): string;

Example​

src/pages/index.js
import React from 'react';
import Layout from '@theme/Layout';

import {translate} from '@docusaurus/Translate';

export default function Home() {
  return (
    <Layout
      title={translate({message: 'My page meta title'})}>
      <img
        src={'https://docusaurus.io/logo.png'}
        aria-label={
          translate(
            {
              message: 'The logo of site {siteName}',
              // Optional
              id: 'homepage.logo.ariaLabel',
              description: 'The home page logo aria label',
            },
            {siteName: 'Docusaurus'},
          )
        }
      />
    </Layout>
  );
}

Modules​

ExecutionEnvironment​

Un module qui expose quelques variables booléennes pour vérifier l'environnement de rendu actuel.

attention

For React rendering logic, use useIsBrowser() or <BrowserOnly> instead.

Exemple :

import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';

if (ExecutionEnvironment.canUseDOM) {
  require('lib-that-only-works-client-side');
}
ChampDescription
ExecutionEnvironment.canUseDOMtrue if on client/browser, false on Node.js/prerendering.
ExecutionEnvironment.canUseEventListenerstrue if on client and has window.addEventListener.
ExecutionEnvironment.canUseIntersectionObservertrue if on client and has IntersectionObserver.
ExecutionEnvironment.canUseViewporttrue if on client and has window.screen.

constants​

Un module exposant des constantes utiles au code du thème côté client.

import {DEFAULT_PLUGIN_ID} from '@docusaurus/constants';
Export nomméValeur
DEFAULT_PLUGIN_IDdefault