Aller au contenu principal
Version: 2.0.0-beta.5 🚧

API client Docusaurus

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

Composants#

<Head/>#

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. Il s'agit d'une enveloppe autour de React Helmet.

Exemple d'utilisation :

import React from 'react';import Head from '@docusaurus/Head';
const MySEO = () => (  <Head>    <meta property="og:description" content="Ma propre description" />    <meta charSet="utf-8" />    <title>Mon titre</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>Mon titre</title>    <meta name="description" content="Helmet application" />  </Head>  <Child>    <Head>      <title>Titre imbriqué</title>      <meta name="description" content="Nested component" />    </Head>  </Child></Parent>

Sorties :

<head>  <title>Titre imbriqué</title>  <meta name="description" content="Nested component" /></head>

<Link/>#

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. Nous utilisons un IntersectionObserver pour récupérer une requête de faible priorité lorsque le <Link> est dans le viewport, puis nous utilisons un événement onMouseOver pour déclencher une requête de haute priorité lorsqu'il est probable qu'un utilisateur navigue vers la ressource demandée.

Ce composant est une enveloppe autour du composant <Link> de react-router qui ajoute des améliorations utiles spécifiques à Docusaurus. Tous les props sont transmis au composant <Link> de react-router.

Les liens externes fonctionnent également, et ont automatiquement ces props : target="_blank" rel="noopener noreferrer".

import React from 'react';import Link from '@docusaurus/Link';
const Page = () => (  <div>    <p>      Consultez mon <Link to="/blog">blog</Link>!    </p>    <p>      Suivez-moi sur <Link to="https://twitter.com/docusaurus">Twitter</Link>!    </p>  </div>);

to : string#

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

<Link to="/courses" />

<Redirect/>#

Rendre un <Redirect> permet de naviguer vers un nouvel emplacement. Le nouvel emplacement remplacera l'emplacement actuel de la pile d'historique, comme le font les redirections côté serveur (HTTP 3xx). Vous pouvez vous référer à la documentation de redirection de React Router pour plus d'informations sur les props disponibles.

Exemple d'utilisation:

import React from 'react';import {Redirect} from '@docusaurus/router';
const Home = () => {  return <Redirect to="/docs/test" />;};
remarque

@docusaurus/router implémente React Router et prend en charge ses fonctionnalités.

<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 window or document objects are being accessed.

Props#

  • children: render function prop returning browser-only JSX. Will not be executed in 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 : texte contenant des placeholders d'interpolation comme {placeholderName}
  • values : objet contenant des valeurs placeholder d'interpolation
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} ! Comment vas-tu ? Jete un œil à mon {website}'}    </Interpolate>  );}

<Translate/>#

Lors de la localisation de votre site, le composant <Translate/> permettra de fournir un support de traduction aux composants React, tels que votre page d'accueil. Le composant <Translate> prend en charge l'interpolation.

Les chaînes de traduction seront extraites de votre code avec la CLI docusaurus write-translations et créeront un fichier de traduction code.json dans website/i18n/<locale>.

remarque

Les props de <Translate/> doivent être des chaînes codées en dur.

Mis à part la prop values utilisée pour l'interpolation, il n'est pas possible d'utiliser des variables, sinon l'extraction statique ne fonctionnerait pas.

Props#

  • children : chaîne non traduite dans la locale par défaut du site (peut contenir des placeholders d'interpolation)
  • id : valeur optionnelle à utiliser comme clé dans les fichiers de traduction JSON
  • description : texte optionnel pour aider le traducteur
  • values : objet optionnel contenant des valeurs placeholder d'interpolation

Exemple#

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

Hooks#

useDocusaurusContext#

Hook de React pour accéder au contexte Docusaurus. Le contexte contient l'objet siteConfig depuis docusaurus.config.js, et quelques métadonnées supplémentaires du site.

type DocusaurusPluginVersionInformation =  | {readonly type: 'package'; readonly version?: string}  | {readonly type: 'project'}  | {readonly type: 'local'}  | {readonly type: 'synthetic'};
interface DocusaurusSiteMetadata {  readonly docusaurusVersion: string;  readonly siteVersion?: string;  readonly pluginVersions: Record<string, DocusaurusPluginVersionInformation>;}
interface I18nLocaleConfig {  label: string;  direction: string;}
interface I18n {  defaultLocale: string;  locales: [string, ...string[]];  currentLocale: string;  localeConfigs: Record<string, I18nLocaleConfig>;}
interface DocusaurusContext {  siteConfig: DocusaurusConfig;  siteMetadata: DocusaurusSiteMetadata;  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>  );};

useIsBrowser#

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

caution

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#

Hook de React pour préfixer le baseUrl de votre site à une chaîne.

caution

Ne l'utilisez pas pour les liens normaux !

Le préfixe /baseUrl/ est automatiquement ajouté à tous les chemins absolus par défaut :

  • Markdown : [link](/my/path) sera lié à /baseUrl/my/path
  • React : <Link to="/my/path/">lien</Link> sera lié à /baseUrl/my/path

Options#

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

Exemple d'utilisation:#

import React from 'react';import useBaseUrl from '@docusaurus/useBaseUrl';
const SomeImage = () => {  const imgSrc = useBaseUrl('/img/myImage.png');  return <img src={imgSrc} />;};
astuce

Dans la plupart des cas, vous n'avez pas besoin de useBaseUrl.

Préférez un appel de require() pour les ressources :

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

useBaseUrlUtils#

Parfois, useBaseUrl n'est pas suffisant. Ce hook retourne des utilitaires supplémentaires liés à l'URL de base de votre site.

  • withBaseUrl : utile si vous avez besoin d'ajouter des URL de base à plusieurs URL à la fois.
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" par défaut    any // données spécifiques au plugin  >>;

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

Inspectez les données globales de votre site depuis ./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 est facultatif si vous n'utilisez pas de plugins multi-instances.

usePluginData(pluginName: string, pluginId?: string)

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.

useAllPluginInstancesData(pluginName: string)

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

Fonctions#

interpolate#

La contrepartie impérative du composant <Interpolate>.

Signature#

// Interpolation simple de chaîne de caractèresfunction interpolate(text: string, values: Record<string, string>): string;
// interpolation JSXfunction interpolate(  text: string,  values: Record<string, ReactNode>,): ReactNode;

Exemple#

import {interpolate} from '@docusaurus/Interpolate';
const message = interpolate('Welcome {firstName}', {firstName: 'Sébastien'});

translate#

La contrepartie impérative du composant <Translate>. Elle prend en charge aussi l'interpolation des placeholders.

astuce

Utilisez l'API impérative pour les rares cas où un composant ne peut pas être utilisé, tels que :

  • la métadonnée title de la page
  • les props placeholder pour des saisies de formulaire
  • les props aria-label- pour l'accessibilité

Signature#

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

Exemple#

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.

caution

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 si sur le client et nous avons window.addEventListener.
ExecutionEnvironment.canUseIntersectionObservertrue si sur le client et nous avons IntersectionObserver.
ExecutionEnvironment.canUseViewporttrue si sur le client et nous avons 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