Skip to main content

DocusaurusのクライアントAPI

Docusaurusは、サイト構築の際に役立つAPIをクライアントに提供しています。

コンポーネント​

<ErrorBoundary />​

このコンポーネントはReactのerror boundaryを作成します。

例外を投げる可能性のあるコンポーネントをくるみ、アプリ全体を機能停止させるのではなく、例外が発生したときにフォールバックを表示するために使用します。

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

const SafeComponent = () => (
  <ErrorBoundary
    fallback={({error, tryAgain}) => (
      <div>
        <p>エラー発生のためコンポーネントが機能停止しました：{error.message}</p>
        <button onClick={tryAgain}>やり直す！</button>
      </div>
    )}>
    <SomeDangerousComponentThatMayThrow />
  </ErrorBoundary>
);
ヒント

動作の様子を見たい場合は、クリックしてみてください→

情報

Docusaurusはこのコンポーネントを使用して、テーマのレイアウトやアプリ全体のエラーを検出します。

メモ

このコンポーネントは、ビルド時のエラーをキャッチせず、ステートフルなReactコンポーネントを使用するときに起こりうるクライアント側のレンダー・エラーのみを防ぎます。

プロパティ​

  • fallback：JSX要素を返す省略可能なレンダーコールバック。 error（捕捉されたエラー）・tryAgain（コンポーネント内のエラーをリセットし、再レンダリングを試みる関数（() => void）コールバック）という2つの属性を持つオブジェクトを受け取ります。 存在しない場合、@theme/Errorが代わりにレンダリングされます。 @theme/Error is used for the error boundaries wrapping the site, above the layout.
警告

fallbackプロパティはコールバックであり、Reactの関数コンポーネントではありません。 このコールバック内ではReactフックを使用できません。

この再利用可能なReactコンポーネントは、ドキュメントのヘッドに対するすべての変更を管理します。 プレーンなHTMLタグを受け取り、プレーンなHTMLタグを出力するため、初心者にも優しいです。 これはReact Helmetのラッパーです。

使用例：

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>サイトのタイトル</title>
    <link rel="canonical" href="http://mysite.com/example" />
  </Head>
);

入れ子または後から追加されたコンポーネントは、重複した内容を上書きします。

<Parent>
  <Head>
    <title>サイトのタイトル</title>
    <meta name="description" content="Helmet application" />
  </Head>
  <Child>
    <Head>
      <title>入れ子のタイトル</title>
      <meta name="description" content="Nested component" />
    </Head>
  </Child>
</Parent>

出力：

<head>
  <title>入れ子のタイトル</title>
  <meta name="description" content="Nested component" />
</head>

This component enables linking to internal pages as well as a powerful performance feature called preloading. Preloading is used to prefetch resources so that the resources are fetched by the time the user navigates with this component. 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​

The target location to navigate to. Example: /docs/introduction.

<Link to="/courses" />
ヒント

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. The new location will override the current location in the history stack like server-side redirects (HTTP 3xx) do. You can refer to React Router's Redirect documentation for more info on available props.

Example usage:

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

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

@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.

ヒント

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

プロパティ​

  • 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.

コード例​

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/>​

A simple interpolation component for text containing dynamic placeholders.

The placeholders will be replaced with the provided dynamic values and JSX elements of your choice (strings, links, styled elements...).

プロパティ​

  • 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].

メモ

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.

プロパティ​

  • 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>
  );
}
メモ

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" />
情報

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

Hooks​

useDocusaurusContext​

React hook to access Docusaurus Context. 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>;
};

Usage example:

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

The siteConfig object only contains serializable values (values that are preserved after JSON.stringify()). 関数や正規表現などはクライアント側では失われます。

useIsBrowser​

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

警告

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.

Usage example:

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.

警告

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} />;
};
ヒント

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. This hook return additional utils related to your site's base URL.

  • 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​

React hook to access Docusaurus global data created by all the plugins.

Global data is namespaced by plugin name then by plugin ID.

情報

Plugin ID is only useful when a plugin is used multiple times on the same site. Each plugin instance is able to create its own global data.

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

Usage example:

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>;
};
ヒント

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

usePluginData​

Access global data created by a specific plugin instance.

This is the most convenient hook to access plugin global data and should be used most of the time.

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

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

Usage example:

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

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

useAllPluginInstancesData​

Access global data created by a specific plugin. Given a plugin name, it returns the data of all the plugins instances of that name, by plugin id.

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

Usage example:

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

React hook to access the Docusaurus broken link checker APIs, exposing a way for a Docusaurus pages to report and collect their links and anchors.

警告

This is an advanced API that most Docusaurus users don't need to use directly.

It is already built-in in existing high-level components:

  • the <Link> component will collect links for you
  • the @theme/Heading (used for Markdown headings) will collect anchors

Use useBrokenLinks() if you implement your own <Heading> or <Link> component.

Usage example:

MyHeading.js
import useBrokenLinks from '@docusaurus/useBrokenLinks';

export default function MyHeading(props) {
  useBrokenLinks().collectAnchor(props.id);
  return <h2 {...props} />;
}
MyLink.js
import useBrokenLinks from '@docusaurus/useBrokenLinks';

export default function MyLink(props) {
  useBrokenLinks().collectLink(props.href);
  return <a {...props} />;
}

関数​

interpolate​

The imperative counterpart of the <Interpolate> component.

シグネチャ​

// 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.

ヒント

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

シグネチャ​

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

モジュール​

ExecutionEnvironment​

A module that exposes a few boolean variables to check the current rendering environment.

警告

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

例：

import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';

if (ExecutionEnvironment.canUseDOM) {
  require('lib-that-only-works-client-side');
}
Field説明
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​

A module exposing useful constants to client-side theme code.

import {DEFAULT_PLUGIN_ID} from '@docusaurus/constants';
Named exportValue
DEFAULT_PLUGIN_IDdefault