redirect

This plugin can automatically handle redirects for your site.

Usage

npm i -D @vuepress/plugin-redirect@next

import { redirectPlugin } from '@vuepress/plugin-redirect'

export default {
  plugins: [
    redirectPlugin({
      // options
    }),
  ],
}

Control Page Redirection

If you change the address of an existing page, you can use the redirectFrom option in Frontmatter to redirect to the address of this page, which ensures that users are redirected to the new address when they visit the old link.

If you need to redirect an existing page to a new page, you can use the redirectTo option in Frontmatter to set the address to redirect to. This way the page will redirect to the new address when accessed.

You can also set config with a redirect map in plugin options, see config for more details.

Auto Locales

The plugin can automatically redirect non-multilingual links to the multilingual pages the user needs based on the user's language preference.

To achieve this, you need to leave the default language directory (/) blank and set autoLocale: true in plugin options. The plugin will automatically redirect to the correct page according to the user's language.

I.E.: you need to set the following directory structure:

.
├── en
│   ├── ...
│   ├── page.md
│   └── README.md
├── zh
│   ├── ...
│   ├── page.md
│   └── README.md
└── other_languages
    ├── ...
    ├── page.md
    └── README.md

And set locales in theme options with:

export default {
  locales: {
    '/en/': {
      lang: 'en-US',
      // ...
    },
    '/zh/': {
      lang: 'zh-CN',
      // ...
    },
    // other languages
  },
  // ...
}

So when a user accesses / or /page.html, they are automatically redirected to /en/ /en/page.html and /en/ /en/page.html based on current browser language.

Automatically switch languages

The plugin supports automatically switching the link to the multilingual page that the user needs according to the user's language preference when opening a multilingual document. In order to achieve this, you need to set switchLocale in the plugin options, which can be the following two values:

• direct: switch directly to the user language preference page without asking
• modal: When the user's language preference is different from the current page language, show a modal asking whether to switch language

Customizing Locale Settings

By default, the plugin generates a locale setting by reading locale path and lang from the site's locales option. Sometimes, you may want multiple languages to hit the same path, in which case you should set localeConfig in plugin options.

For example, you might want all English users to match to /en/ and Chinese Traditional users to /zh/, then you can set:

redirect({
  localeConfig: {
    '/en/': ['en-US', 'en-UK', 'en'],
    '/zh/': ['zh-CN', 'zh-TW', 'zh'],
  },
})

Redirecting Sites

Sometimes you may change base or use new domain for your site, so you may want the original site automatically redirects to the new one.

To solve this, the plugin provide vp-redirect cli.

Usage: vp-redirect [options] <source> [output]

Generate redirect site for current VuePress project

Arguments:
  source                 Source directory of VuePress project
  output                 Output folder (default: .vuepress/redirect relative to source folder)

Options:
  --hostname <hostname>  Hostname to redirect to (E.g.: https://new.example.com/) (default: "/")
  -c, --config [config]  Set path to config file
  --cache [cache]        Set the directory of the cache files
  --temp [temp]          Set the directory of the temporary files
  --clean-cache          Clean the cache files before generation
  --clean-temp           Clean the temporary files before generation
  -V, --version          output the version number
  -h, --help             display help for command

You need to pass in VuePress project source dir and also set the hostname option. The redirect helper cli will initialize your VuePress project to get pages, then generate and output the redirect html files to the output directory.

By default, the plugin will output to .vuepress/redirect directory under source directory. And you should upload it to your original site to provide redirection.

Options

config

• Type: Record<string, string> | ((app: App) => Record<string, string>)

• Details: Redirect map.

• Example:

  When base is set to /base/:

  • redirect /base/foo.html to /base/bar.html
  • /base/baz.html to https://example.com/qux.html.

  redirect({
    config: {
      '/foo.html': '/bar.html',
      '/baz.html': 'https://example.com/qux.html',
    },
  })

  Redirect post folder to posts folder:

  redirect({
    hostname: 'https://example.com',
    config: (app) =>
      Object.fromEntries(
        app.pages
          .filter(({ path }) => path.startsWith('/posts/'))
          .map(({ path }) => [path.replace(/^\/posts\//, '/post/'), path]),
      ),
  })

autoLocale

• Type: boolean
• Default: false
• Details: Whether enable locales redirection.

switchLocale

• Type: "direct" | "modal" | false

• Default: false

• Details:

  Whether switch to a new locale based on user preference.

  • "direct": redirect to the new locale directly without asking
  • "modal": show a modal to let user choose whether to switch to the new locale

localeConfig

• Type: Record<string, string | string[]>

• Details: Locale language config

localeFallback

• Type: boolean
• Default: true
• Details: Whether fallback to other locales user defined

defaultBehavior

• Type: "defaultLocale" | "homepage" | "404"
• Default: "defaultLocale"
• Details: Behavior when a locale version is not available for current link.

defaultLocale

• Type: string

• Default: the first locale

• Details: Default locale path.

• Type: RedirectPluginLocaleConfig

  interface RedirectPluginLocaleData {
    /**
     * Language name
     */
    name: string
  
    /**
     * Switch hint
     */
    hint: string
  
    /**
     * Switch button text
     */
    switch: string
  
    /**
     * Cancel button text
     */
    cancel: string
  
    /**
     * remember hint text
     */
    remember: string
  }
  
  interface RedirectPluginLocaleConfig {
    [localePath: string]: Partial<RedirectPluginLocaleData>
  }

• Details:

  Locales config for redirect plugin.

Frontmatter

redirectFrom

• Type: string | string[]
• Details: The link which this page redirects from.

redirectTo

• Type: string
• Details: The link which this page redirects to.

Styles

You can customize the style of the redirect popup via CSS variables:

:root {
  --redirect-z-index: 1499;
  --redirect-c-bg: var(--vp-c-bg-elv);
  --redirect-c-text: var(--vp-c-text);
  --redirect-c-accent-bg: var(--vp-c-accent-bg);
  --redirect-c-accent-hover: var(--vp-c-accent-hover);
  --redirect-c-accent-text: var(--vp-c-accent-text);
  --redirect-c-control: var(--vp-c-control);
  --redirect-c-control-hover: var(--vp-c-control-hover);
  --redirect-c-shadow: var(--vp-c-shadow);
}