How to use lifecycle-apis#actions

[ghost]

Hi again
I am still trying to get adoption within our company higher for 🦖

One question that came up (when migrating from Jekyll to Docusaurus) is how to keep ancient URLs a a little bit backward compatible (like the most important 10).

Old	New
baseUrl/housekeeping.html	baseUrl/docs/folder/housekeeping
baseUrl/security.html	baseUrl/docs/folder2/security

I try to use https://docusaurus.io/docs/lifecycle-apis#actions but to me it s a bit unclear where to hook into the lifecycle. I want to teach Docusaurus that at baseUrl/housekeeping.html he should route to a defined docs page.

It would be sufficient for me if I can tell 🦖 to add like 10 routes which map an old xxx.html to a new nested docs page.

We tried already to just use slug: /housekeeping.html but it breaks in two ways:

• We can't nest it cleanly and properly
• https://github.com/easyops-cn/docusaurus-search-local crashes on build as it thinks .html is a file while its a directory

Any help on that matter would be appreciated 👍🏼

[slorber]

One question that came up (when migrating from Jekyll to Docusaurus) is how to keep ancient URLs a a little bit backward compatible (like the most important 10).

You want a redirect.
Remember server-side redirects are always better than client-side redirects.
And they must be configured on your hosting provider. (if you use GitHub pages it's not possible, but it is on other hosts that I recommend such as Vercel/Netlify)

actions allows you to create a React page.
On this page you could do a client-side redirect (with js / React-Router's Redirect component) but it's not a good idea because that redirect would be slow (it would have to load React, hydrate it even before doing the redirect).

We have a client-side redirect plugin: https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-client-redirects
It will create lightweight redirect files that will be faster than using a redirect from a React page.

This is basically a shortcut and exactly the same as adding manually a small static/housekeeping.html file on which you just add some JS like window.location.href = '/docs/folder/housekeeping';

So TLDR:

• Always prefer server-side redirects (perf, SEO...). Consider using a better host if needed.
• When not possible, use lightweight client-side redirects
• Try our client-side redirect plugin
• If the plugin is not good for your use-case, write redirect files manually in static (eventually write a script to generate those redirect files)
• Avoid using actions, it's not meant to create redirects

[slorber]

Other notes:

• Using slug frontmatter, you'll still have the /docs/ prefix in front of the doc slug. But you can configure this prefix and make it / if you want (with routeBasePath config. I think we call this "docs-only mode" in the doc but it's more "docs-at-the-root" in practice)
• We don't maintain docusaurus-search-local, if it crashes it's not our responsibility to fix and you should mention your problem directly to this repo
• Using the trailingSlash config might help, as it controls output filenames: it might enable to change output from housekeeping.html vs housekeeping.html/index.html

[ghost]

Thanks @slorber
For our humble use case (keeping like 7 ultra important URLs backward compatible) the following combination did it all:

• https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-client-redirects
• Using routeBasePath to pull up /docs, made it /

🥳