Version: 2.0.0-alpha.72

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.

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

const Page = () => (
  <div>
    <p>
      Consultez mon <Link to="/blog">blog</Link>!
    </p>
    <p>
      {/*  Notez que les liens externes utilisent toujours des balises `a`, mais s'ouvre automatiquement dans un nouvel onglet. */}
      Suivez moi sur <a href="https://twitter.com/docusaurus">Twitter</a>!
    </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/>`#

Le composant <BrowserOnly> accepte une prop children , une fonction de rendu qui ne sera pas exécutée pendant la phase de pré-rendu du processus de compilation. Ceci est utile pour cacher le code qui n'est destiné qu'à s'exécuter dans les navigateurs (par exemple, là où l'on accède aux objets window/document). Pour améliorer le référencement, vous pouvez également fournir un contenu de repli en utilisant le prop fallback, qui sera prérendu jusqu'au processus de construction et remplacé par le contenu côté client uniquement lors de l'affichage dans le navigateur.

import BrowserOnly from '@docusaurus/BrowserOnly';

const MyComponent = () => {
  return (
    <BrowserOnly
      fallback={<div>Le contenu de repli à afficher lors du prérendu.</div>}>
      {() => {
        // Quelque chose qui doit être exclu pendant le pré-rendu du processus de construction.
      }}
    </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 le CLI docusaurus write-translations et créera 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 DocusaurusContext {
  siteConfig: DocusaurusConfig;
  siteMetadata: DocusaurusSiteMetadata;
}

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

`useBaseUrl`#

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

attention

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ères
function interpolate(text: string, values: Record<string, string>): string;

// interpolation JSX
function 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. Utile si vous voulez n'exécuter que du code sur le client/serveur ou si vous avez besoin d'écrire du code compatible avec le rendu côté serveur.

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

const MyPage = () => {
  const location = ExecutionEnvironment.canUseDOM ? window.location.href : null;
  return <div>{location}</div>;
};

Champ	Description
`ExecutionEnvironment.canUseDOM`	`true` si sur le client, `false` si c'est le pré-rendu.
`ExecutionEnvironment.canUseEventListeners`	`true` si sur le client et nous avons `window.addEventListener`.
`ExecutionEnvironment.canUseIntersectionObserver`	`true` si sur le client et nous avons `IntersectionObserver`.
`ExecutionEnvironment.canUseViewport`	`true` 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_ID`	`default`

Composants#

<Head/>#

<Link/>#

to : string#

<Redirect/>#

remarque

<BrowserOnly/>#

<Interpolate/>#

Props#

<Translate/>#

remarque

Props#

Exemple#

Hooks#

useDocusaurusContext#

useBaseUrl#

attention

Options#

Exemple d'utilisation:#

astuce

useBaseUrlUtils#

useGlobalData#

info

astuce

usePluginData#

useAllPluginInstancesData#

Fonctions#

interpolate#

Signature#

Exemple#

translate#

astuce

Signature#

Exemple#

Modules#

ExecutionEnvironment#

constants#

`<Head/>`#

`<Link/>`#

`to` : string#

`<Redirect/>`#

`<BrowserOnly/>`#

`<Interpolate/>`#

`<Translate/>`#

`useDocusaurusContext`#

`useBaseUrl`#

`useBaseUrlUtils`#

`useGlobalData`#

`usePluginData`#

`useAllPluginInstancesData`#

`interpolate`#

`translate`#

`ExecutionEnvironment`#

`constants`#