📦 plugin-client-redirects

클라이언트 측 리디렉션을 생성하는 도큐사우루스 플러그인입니다.

플러그인에서는 자바스크립트로 만든 도큐사우루스 페이지로 리다이렉트할 수 있도록 여러분의 정적인 사이트에 HTML 페이지를 추가로 만듭니다.

production only

이 플러그인은 빌드 결과물을 대상으로 동작하므로 개발 환경에서는 항상 비활성화되며 프로덕션에서만 활성화됩니다.

경고

가능하다면 서버 측 리다이렉트를 사용하는 것을 권장합니다.

플러그인을 사용하기 전에 여러분의 호스트 서비스 업체게 이 기능을 지원하지 않는지 먼저 확인해보세요.

설치

npm

npm install --save @docusaurus/plugin-client-redirects

Yarn

yarn add @docusaurus/plugin-client-redirects

pnpm

pnpm add @docusaurus/plugin-client-redirects

Bun

bun add @docusaurus/plugin-client-redirects

설정

설정할 수 있는 필드

옵션	타입	기본값	설명
fromExtensions	string[]	[]	리다이렉트 후 경로에서 제거할 확장자입니다.
toExtensions	string[]	[]	리다이렉트 후 경로에 추가할 확장자입니다.
redirects	RedirectRule[]	[]	리다이렉트 규칙 목록입니다.
createRedirects	CreateRedirectsFn	undefined	리다이렉트 규칙을 만들기 위한 콜백입니다. 도큐사우루스는 생성한 모든 경로에 대해 콜백을 요청하고 반환값을 사용해 더 많은 경로를 출력합니다.

참고

이 플러그인은 여러 파일이 같은 위치에 생성될 때 로그 수준을 조정하기 위해 siteConfig.onDuplicateRoutes 설정도 읽습니다.

타입

RedirectRule

type RedirectRule = {
  to: string;
  from: string | string[];
};

참고

"from"과 "to"의 개념은 이 플러그인의 핵심입니다. "from"은 생성하려는 경로, 즉 새로 작성될 HTML 파일을 의미합니다. "to"는 리디렉션할 대상 경로를 의미하며, 보통 도큐사우루스가 이미 알고 있는 경로입니다.

이 때문에 같은 "to"에 대해 여러 개의 "from"을 가질 수 있습니다. 모두 같은 목적지로 리다이렉트되는 여러 개의 HTML 파일을 생성합니다. 반면에 "from"은 하나보다 많은 "to"를 가질 수 없습니다. 작성된 HTML 파일은 명확한 목적지가 있어야 합니다.

CreateRedirectsFn

// `path` 매개변수는 도큐사우루스가 이미 생성한 경로이며 "to"에 해당합니다.
// 반환값은 "from"에 해당합니다. falsy 값을 반환하면 이 경로에 대한
// 리디렉션 페이지를 생성하지 않습니다.
type CreateRedirectsFn = (path: string) => string[] | string | null | undefined;

설정 예시

다음은 설정 예시입니다:

docusaurus.config.js

export default {
  plugins: [
    [
      '@docusaurus/plugin-client-redirects',
      {
        fromExtensions: ['html', 'htm'], // /myPage.html -> /myPage
        toExtensions: ['exe', 'zip'], // /myAsset -> /myAsset.zip (후자가 존재하는 경우)
        redirects: [
          // /docs/oldDoc -> /docs/newDoc
          {
            to: '/docs/newDoc',
            from: '/docs/oldDoc',
          },
          // 여러 이전 경로에서 새 경로로 리디렉션
          {
            to: '/docs/newDoc2',
            from: ['/docs/oldDocFrom2019', '/docs/legacyDocFrom2016'],
          },
        ],
        createRedirects(existingPath) {
          if (existingPath.includes('/community')) {
            // /docs/team/X와 /docs/support/X에서 /community/X로 리디렉션
            return [
              existingPath.replace('/community', '/docs/team'),
              existingPath.replace('/community', '/docs/support'),
            ];
          }
          return undefined; // falsy 값을 반환하면 리디렉션을 생성하지 않습니다
        },
      },
    ],
  ],
};