📦 plugin-client-redirects

클라이언트 리다이렉트를 처리하기 위한 도큐사우루스 플러그인입니다.

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

production only

해당 플러그인은 빌드 산출물에서만 작동하기 때문에 개발 중에는 비활성화되고 제품 빌드 시에만 활성화됩니다.

warning

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

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

설치

npm

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

Yarn

yarn add @docusaurus/plugin-client-redirects

pnpm

pnpm 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"이 됩니다. 거짓 값을 반환하면
// 특정 경로에 대한 리다이렉트 페이지가 생성되지 않습니다.
type CreateRedirectsFn = (path: string) => string[] | string | null | undefined;

설정 예시

다음은 설정 예시입니다:

docusaurus.config.js

module.exports = {
  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에서 /community/X로 그리고 /docs/support/X에서 /community/X로 리다이렉트
            return [
              existingPath.replace('/community', '/docs/team'),
              existingPath.replace('/community', '/docs/support'),
            ];
          }
          return undefined; // 잘못된 값 반환: 리다이렉트가 만들어지지 않음
        },
      },
    ],
  ],
};