[2.0] RFC: docusaurus swizzle --wrap/copy

🚀 Feature

We have a feature to wrap existing theme components: https://docusaurus.io/docs/using-themes#wrapping-theme-components

import OriginalFooter from "@theme-original/Footer";
import React from "react";

export default function Footer(props) {
  return (
    <>
      <div>Before footer</div>
      <OriginalFooter {...props} />
    </>
  );
}

It’s a very useful pattern to use to customize your Docusaurus site. It allows you to enhance a Docusaurus theme without having to copy (and maintain) theme code.

Unfortunately, this feature is not very visible and we don’t encourage its usage, as the code above is only found in our doc, and the swizzle CLI command does not produce such code.

Some use-cases:

• Add a custom comp before/after (above/under) any existing theme component (like add comments to blog posts)
• Slightly modify the layout/behavior of an existing theme component (like, add line numbers to code blocks)
• Add custom MDX components

---

I suggest to do some changes:

• Add a docusaurus swizzle --wrap option to produce such code. It wouldn’t require the usage of --danger because it’s way safer than copying.
• For copying, require explicit usage of --copy option, keep --danger for unsafe components and suggest to prefer usage of --wrap
• No option: suggest use either --wrap or --copy, hint to prefer --wrap

---

Other changes to consider in the long term:

• Rename docusaurus swizzle to something more intuitive like docusaurus theme?
• Create much smaller theme components, so that users naturally have more before/after wrapping possibilities to suit their use-cases.

[Josh-Cena]

Great, you can go ahead 👍 I would be relaxing a little

[Josh-Cena]

Rename docusaurus swizzle to something more intuitive like docusaurus theme?

1. I like swizzle because it sounds funky 😛
2. We probably want a verb here instead of a noun
3. Agree that swizzle is not intuitive enough

Create much smaller theme components, so that users naturally have more before/after wrapping possibilities to suit their use-cases.

Agreed. I also think a more hierarchical component structure is better than crowding src/theme with all kinds of components, since it makes navigation and understanding the components’ usage easier.

No strong feelings about extending the CLI. I think we can make it fully interactive (just like docusaurus-init) so that running docusaurus swizzle will prompt you for wrap/copy, the theme, and the component, step by step. Right now if the theme name / component name isn’t provided it throws an exit code: 1 in my face which I don’t like. If user just wants to list the components/themes available but not to actually choose any of them, they can either provide an explicit --list argument or choose a quit option in the interactive console.