메인 컨텐츠로 이동
버전: 불안정 🚧

도큐사우루스 클라이언트 API

도큐사우루스는 사이트를 만들 때 도움이 될 만한 API를 클라이언트에서 사용할 수 있게 제공합니다.

컴포넌트

<ErrorBoundary />

이 컴포넌트는 리액트 에러 경계를 만듭니다.

이를 사용해 컴포넌트를 래핑하고 에러가 발생했을 때 전체 앱 오류로 처리하는 대신 대체할 수 있는 UI를 보여줄 수 있습니다.

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

동작을 확인하려면 클릭해보세요.

정보

도큐사우루스는 해당 컴포넌트를 사용해 테마 레이아웃과 전체 앱에서 발생하는 오류를 처리할 수 있습니다.

참고

해당 컴포넌트는 빌드 시 오류는 처리하지 않으며 안정된 리액트 컴포넌트 사용 시 발생할 수 있는 클라이언트 측 렌더링 오류에 대해서만 처리합니다.

속성

  • fallback: JSX 요소를 반환하는 렌더 콜백 옵션입니다. 두 개의 속성을 가진 오브젝트를 받을 수 있습니다. error는 처리할 에러 그리고 tryAgain는 컴포넌트 내에서 에러를 초기화하고 다시 렌더링하기 위한 콜백 함수(() => void)입니다. 반환되는 것이 없다면 @theme/Error에서 대신 렌더링합니다. @theme/Error는 레이아웃 위에서 사이트를 래핑하는 에러 경계(Error Boundaries)로 사용됩니다.
경고

fallback 속성은 콜백이며 리액트 기능 컴포넌트가 아닙니다. 콜백 내에서 리액트 후크를 사용할 수 없습니다.

재사용할 수 있는 리액트 컴포넌트로 문서 헤더 영역의 수정을 관리할 수 있습니다. 일반적인 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>My Title</title>
<link rel="canonical" href="http://mysite.com/example" />
</Head>
);

중첩되거나 나중에 정의된 컴포넌트는 이전 값을 덮어씁니다.

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

출력 결과는 아래와 같습니다.

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

내부 페이지에 연결하거나 미리 콘텐츠를 불러와서(preloading) 성능을 최적화할 수 있는 기능을 사용할 수 있습니다. 사전 로딩(preloading)은 사용자가 컴포넌트를 사용하는 시점에 필요한 리소스를 미리 가져오는 방식입니다. <Link>가 viewport 내에 있을 때 낮은 우선순위의 요청을 처리하기 위해 IntersectionObserver를 사용합니다. 그리고 사용자가 높은 우선순위의 리소스를 요청하려고 할 때는 onMouseOver 이벤트를 발생시킵니다.

리액트 라우터의 <Link>의 래퍼 컴포넌트이며 도큐사우루스 특성에 맞게 몇 가지 유용한 기능을 확장했스니다. 모든 속성 설정은 리액트 라우터의 <Link> 컴포넌트로 전달됩니다.

외부 링크에도 적용할 수 있습니다. 자동으로 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://x.com/docusaurus">X</Link>!
</p>
</div>
);

to: string

탐색할 주소를 설정합니다. 예를 들어 /docs/introduction 같은 형식입니다.

<Link to="/courses" />

<Link>를 사용하면 도큐사우루스에서 많은 부분 최적화(예. 깨진 경로 감지, 프리페칭, base URL 적용 등)를 처리해주기 때문에 <a> 태그보다 이 컴포넌트를 권장합니다.

<Redirect/>

<Redirect>은 새로운 주소의 콘텐츠로 바로 가기 위해 사용합니다. 새로운 주소는 방문 기록 상 현재 주소를 덮어씁니다. 마치 서버에서 리다이렉트(HTTP 3xx)를 처리하는 것과 같습니다. 사용할 수 있는 속성에 대해서는 리액트 라우터의 리다이렉트 문서를 참고하세요.

Example usage:

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

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

@docusaurus/router리액트 라우터 기반으로 모든 기능을 지원합니다.

<BrowserOnly/>

<BrowserOnly> 컴포넌트는 리액트 앱이 하이드레이트되면 브라우저에서만 리액트 컴포넌트를 렌더링하도록 허용합니다.

window 또는 document 오브젝트에 액세스한 상태에서 Node.js에서 실행할 수 없는 코드와 통합을 위해 사용합니다.

속성

  • children: 브라우저 전용 JSX를 반환하는 렌더링 함수 속성입니다. Node.js에서는 실행되지 않습니다.
  • fallback (옵션): 리액트 하이드레이트가 완료되기전까지 서버(Node.js)에서 렌더링할 JSX입니다.

예시 코드

import BrowserOnly from '@docusaurus/BrowserOnly';

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

라이브러리를 사용한 예시 코드

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

동적으로 표시되는 자리표시자(placeholder)를 포함한 텍스트를 위한 간단한 컴포넌트입니다.

자리표시자는 동적으로 처리되는 값과 여러분이 선택한 JSX 요소(문자열, 링크, 스타일 요소 등)을 대체합니다.

속성

  • children: {placeholderName} 형태로 작성한 자리표시자를 포함한 텍스트입니다.
  • 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/>

여러분의 사이트를 현지화할 때 <Translate/> 컴포넌트는 홈페이지 같은 리액트 컴포넌트에 대한 번역을 지원합니다. <Translate> 컴포넌트는 interpolation를 지원합니다.

docusaurus write-translations 명령을 통해 번역할 문자열을 여러분의 코드에서 추출하고 website/i18n/[locale] 디렉터리 아래에 code.json 파일을 만듭니다.

참고

<Translate/> 속성은 직접 입력된 문자열이어야 합니다.

interpolation 처리를 위한 values을 제외하고는 **변수를 사용할 수 없으며 ** 정적인 추출법(static extraction)도 동작하지 않습니다.

속성

  • children: 사이트 기본 로케일 설정에 따라 번역되지 않은 문자열(interpolation placeholders을 포함할 수 있습니다)
  • id: JSON 번역 파일에서 키 값으로 사용하는 값(필수는 아님)
  • description: 번역자가 참조할 수 있는 설명(필수는 아님)
  • values: 자리표시자를 처리할 값을 포함한 오브젝트(필수는 아님)

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

docusaurus write-translations CLI 명령을 실행한 후 자식 속성을 생략하고 code.json 파일에 번역 문자열을 수동으로 설정할 수 있습니다.

<Translate id="homepage.title" />
정보

<Translate> 컴포넌트는 interpolation를 지원합니다. 일부 사용자 정의 코드와 translate imperative API를 통해 문자열 단/복수 처리를 구현할 수 있습니다.

후크

useDocusaurusContext

도큐사우루스 컨텍스트에 접근하기 위한 리액트 후크입니다. 컨텍스트는 docusaurus.config.js 파일에 설정한 siteConfig 오브젝트와 사이트에서 사용하는 메타데이터를 포함합니다.

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

사용 예:

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

siteConfig 오브젝트에는 직렬화할 수 있는 값(JSON.stringify() 호출 이후 보존되는 값)이 포함됩니다. 함수와 정규식 등은 클라이언트 쪽에서 손실됩니다.

useIsBrowser

리액트 앱이 브라우저에서 성공적으로 하이드레이트되면 true를 반환합니다.

경고

리액트 렌더링 로직에서 typeof windows !== 'undefined' 대신 이 후크를 사용하세요.

첫 번째 클라이언트 측 렌더링 출력(브라우저에서)은 서버 측 렌더링 출력(Node.js)와 정확히 같아야 합니다. 그렇지 않으면 The Perils of Rehydration에서 설명하는 것처럼 의도하지 않은 하이드레이트가 동작할 수 있습니다.

사용 예:

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

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

useBaseUrl

여러분의 사이트 baseUrl에 문자열을 추가하기 위한 리액트 후크입니다.

경고

일반 링크에는 사용하지 마세요!

/baseUrl/ 접두사는 모든 절대 경로에 자동으로 추가됩니다.

  • 마크다운: [link](/my/path)/baseUrl/my/path에 링크가 연결됩니다.
  • 리액트: <Link to="/my/path/">link</Link>/baseUrl/my/path에 링크가 연결됩니다.

옵션

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

대부분의 경우 useBaseUrl을 사용할 일은 없습니다.

아래와 같이 require() 메소드를 사용해 필요한 애셋을 호출하세요.

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

useBaseUrlUtils

useBaseUrl만 사용하기에는 충분하지 않습니다. 여러분의 사이트 base URL과 관련된 추가 유틸을 반환하는 후크입니다.

  • withBaseUrl: 여러 URL에 한 번에 base URL을 추가해야 할 때 유용합니다.
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

모든 플러그인에서 만든 도큐사우루스 전역 데이터에 접근하기 위한 리액트 후크입니다.

전역 데이터는 플러그인의 이름, ID로 네임스페이스가 지정됩니다.

정보

플러그인 ID는 같은 사이트에서 플러그인을 여러 번 사용할 때만 유용합니다. 각 플러그인 인스턴스는 자신만의 전역 데이터를 만들 수 있습니다.

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

사용 예:

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

특정 플러그인 인스턴스에서 만든 전역 데이터에 접근합니다.

플러그인 전역 데이터에 접근하기 위해 가장 편리하고 많이 사용하는 후크입니다.

멀티 인스턴스 플러그인을 사용하지 않는다면 pluginId은 설정하지 않아도 됩니다.

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

사용 예:

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

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

useAllPluginInstancesData

특정 플러그인에서 만든 전역 데이터에 접근합니다. 플러그인 이름을 지정하면 같은 이름을 가지는 모든 플러그인 인스턴스의 데이터를 id별로 반환합니다.

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

사용 예:

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.

사용 예:

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

<Interpolate> 컴포넌트에 대응하는 함수입니다.

시그니처

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

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

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

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

translate

<Translate> 컴포넌트에 대응하는 함수입니다. 자리표시자 기능도 지원합니다.

Use the imperative API for the 아래와 같이 간혹 컴포넌트를 사용할 수 없는 경우 함수 API를 사용할 수 있습니다.

  • 페이지의 title 메타데이터
  • 입력 폼에서 placeholder 속성
  • 접근성에서 aria-label 속성

시그니처

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

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

현재 렌더링 환경을 확인하기 위해 사용할 수 있는 몇 가지 상태 변수를 제공하는 모듈입니다.

경고

리액트 렌더링 로직의 경우 useIsBrowser() 또는 <BrowserOnly>을 사용하세요.

예:

import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';

if (ExecutionEnvironment.canUseDOM) {
require('lib-that-only-works-client-side');
}
Field설명
ExecutionEnvironment.canUseDOM클라이언트/브라우저에서는 true를 반환하고 Node.js/사전 렌더링 시에는 false를 반환합니다.
ExecutionEnvironment.canUseEventListeners클라이언트에서 window.addEventListener를 가지고 있다면 true를 반환합니다.
ExecutionEnvironment.canUseIntersectionObserver클라이언트에서 IntersectionObserver를 가지고 있다면 true를 반환합니다.
ExecutionEnvironment.canUseViewport클라이언트에서 window.screen을 가지고 있다면 true를 반환합니다.

constants

클라이언트 측 테마 코드에 유용한 상수를 제공하는 모듈입니다.

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