Version: 2.0.0-beta.3

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

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

컴포넌트#

`<Head/>`#

재사용할 수 있는 리액트 컴포넌트로 문서 헤더 영역의 수정을 관리할 수 있습니다. 일반적인 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>

`<Link/>`#

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

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

import React from 'react';import Link from '@docusaurus/Link';
const Page = () => (  <div>    <p>      Check out my <Link to="/blog">blog</Link>!    </p>    <p>      {/* 외부 링크는 `a` 태그를 사용하며 외부 링크는 자동으로 새 탭에 열립니다. */}      Follow me on <a href="https://twitter.com/docusaurus">Twitter</a>!    </p>  </div>);

`to`: string#

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

<Link to="/courses" />

`<Redirect/>`#

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

예를 들어 아래와 같이 설정할 수 있습니다.

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

note

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

`<BrowserOnly/>`#

The <BrowserOnly> 컴포넌트는 빌드 프로세스 처리 시 사전 렌더링 단계에서 렌더 함수가 실행하지 않을 children 속성을 설정합니다. 브라우저에서만 동작하는 코드를 숨기는 용도로 유용합니다(예를 들면 window/document 오브젝트에 접근해야 할 때). 검색엔진최적화를 위해 fallback 속성을 사용해 대체 콘텐츠를 제공할 수도 있습니다. 해당 속성을 사용하면 빌드 프로세스까지는 미리 렌더링되고 클라이언트 쪽에서 브라우저를 통해 보게 되는 콘텐츠를 대체할 수 있습니다.

import BrowserOnly from '@docusaurus/BrowserOnly';
const MyComponent = () => {  return (    <BrowserOnly      fallback={<div>The fallback content to display on prerendering</div>}>      {() => {        // 빌드 프로세스 사전 렌더링 처리 시에 대상에서 제외해야 하는 항목      }}    </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 파일을 만듭니다.

note

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

후크#

`useDocusaurusContext`#

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

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

사용 예:

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

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

caution

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

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

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

옵션#

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

예를 들어 아래와 같이 설정할 수 있습니다.#

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

tip

대부분의 경우 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로 네임스페이스가 지정됩니다.

info

플러그인 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>;};

tip

./docusaurus/globalData.json에서 여러분의 사이트에서 사용하는 전역 데이터를 확인할 수 있습니다.

`usePluginData`#

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

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

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

usePluginData(pluginName: string, pluginId?: string)

사용 예:

import React from 'react';import {usePluginData} from '@docusaurus/useGlobalData';
const MyComponent = () => {  const myPluginData = usePluginData('my-plugin');  return <div>{myPluginData.someAttribute}</div>;};

`useAllPluginInstancesData`#

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

useAllPluginInstancesData(pluginName: string)

사용 예:

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

함수#

`interpolate`#

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

시그니처#

// Simple string interpolationfunction interpolate(text: string, values: Record<string, string>): string;
// JSX interpolationfunction interpolate(  text: string,  values: Record<string, ReactNode>,): ReactNode;

예#

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

`translate`#

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

tip

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

현재 렌더링 환경을 확인하기 위해 사용할 수 있는 몇 가지 상태 변수를 제공하는 모듈입니다. 서버/클라이언트 환경에서 특정 코드를 실행하거나 서버 측 렌더링 호환 코드를 작성해야 할 때 유용하게 사용합니다.

import React from 'react';import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
const MyPage = () => {  const location = ExecutionEnvironment.canUseDOM ? window.location.href : null;  return <div>{location}</div>;};

Field	설명
`ExecutionEnvironment.canUseDOM`	클라이언트에서는 `true`를 반환하고 사전 렌더링 시에는 `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_ID`	`default`

컴포넌트#

<Head/>#

<Link/>#

to: string#

<Redirect/>#

note

<BrowserOnly/>#

<Interpolate/>#

속성#

<Translate/>#

note

속성#

예#

후크#

useDocusaurusContext#

useBaseUrl#

caution

옵션#

예를 들어 아래와 같이 설정할 수 있습니다.#

tip

useBaseUrlUtils#

useGlobalData#

info

tip

usePluginData#

useAllPluginInstancesData#

함수#

interpolate#

시그니처#

예#

translate#

tip

시그니처#

예#

모듈#

ExecutionEnvironment#

constants#

`<Head/>`#

`<Link/>`#

`to`: string#

`<Redirect/>`#

`<BrowserOnly/>`#

`<Interpolate/>`#

`<Translate/>`#

`useDocusaurusContext`#

`useBaseUrl`#

`useBaseUrlUtils`#

`useGlobalData`#

`usePluginData`#

`useAllPluginInstancesData`#

`interpolate`#

`translate`#

`ExecutionEnvironment`#

`constants`#