Adding custom component to every docs page

[lanegoolsby]

Hi!

I'm trying to add a custom component directly under the table of contents. The custom component will do some AJAX calls to an internal API and display a short list of results.

I figured out how to swizzle/wrap the TOC component and that works fine.

I have two questions with this approach though:

1. Since TOC isn't marked safe to swizzle, is there a better approach?
2. We will be adding this same custom component to at least two internal Docusaurus sites. What's the best way to package this change so that I don't have to copy swizzled code between two code bases?

I suspect the answer to # 2 is to write a custom plugin but the docs aren't quite clear if I should create a plugin or a theme, nor are they clear on how exactly I'd go about controlling where the component gets put on the page.

[lanegoolsby]

Nevermind, I was poking around in the community plugins and figured out the answer.

[slorber]

Since TOC isn't marked safe to swizzle, is there a better approach?

By default, all our theme components are marked as unsafe (until we are ready to mark them as safe). I wouldn't worry too much, it's just a way for us to signal that we may do breaking changes on their APIs. The word "unsafe" is probably a bit too strong and frightening here, we'll look into a way to make it less scary in the future.

We will be adding this same custom component to at least two internal Docusaurus sites. What's the best way to package this change so that I don't have to copy swizzled code between two code bases?

You can create a theme with just your reusable components, and use a @theme/MyCustomComponent import

You can as well use a monorepo and have a @myCompany/sharedComponentsLib package from which you import things

[lanegoolsby]

Thanks @slorber! I have a question in StackExchange with a problem I'm having in trying to go the reusable component route. Mind taking a look please?

[slorber]

Not sure what's your setup but I'd recommend using Yarn/npm workspaces if you plan to have multiple projects using a shared component library. If you have one node_module per package, that generally leads to bad situations (unless you publish your packages to npm before loading them in the final project)

[lanegoolsby]

I'll be pushing the package to an internal npm registry eventually. I'm just trying to setup my local dev env.

I'm using the folder structure that a lot of the custom plugins are using (for example) where the source is at the root and there is an example site setup for testing.

[slorber]

I'm using the folder structure that a lot of the custom plugins are using (for example) where the source is at the root and there is an example site setup for testing.

I'm not sure this example is so great, because it's not usual to have one package inside the other. The more common approach is to separate those 2.

But maybe it's fine, I don't have a practical experience with this setup. @RDIL ?

Note the root package.json still uses a workspace:

    "workspaces": [
        "testsite"
    ],

[RDIL]

The plugin template uses workspaces because that way you don't have to run install twice. The test site itself is a stub package, and separated so that you don't actually use it unless you actually want to.

If your goal is to have the plugin along-side an existing website codebase, I would suggest copying the template, deleting the testsite, and adding the plugin as either a subpackage, or part of the website's package.

[RDIL]

To clarify, I mean copying the part from src and dropping that in, say, src/plugins/plugin-name. That way, the plugin exists along side your website's other source files.

[lanegoolsby]

Thanks for the suggestions @slorber and @RDIL! They helped tremendously.

Attached is a working proof of concept for what I'm trying to do. Pull the file, unzip it, then run these commands:

custom_plugin.zip

1. yarn install
2. cd plugin
3. tsc
4. cd ../testSite
5. yarn start

(I know I can script all that, I'm trying to keep this as bare-bones as possible)

Seems that either A) upgrading yarn to latest or B) switching to a workspace did the trick.

If I could get thoughts and opinions on if there are more appropriate avenues to achieve what I'm trying to do I'd appreciate it.

But basically what's currently the RocketTOC component will end up being a dynamically generated list of results from an API call using the array returned by useDoc().frontMatter.tags as input.

[slorber]

It's both time consuming and a security concern for me to run your code this way

Please make it easy for me and host it on GitHub where we can inspect it in the browser easily, and eventually run it with 1 click on a StackBlitz sandbox.

See for example: https://stackblitz.com/github/facebook/docusaurus/tree/main/examples/classic

---

Your setup looks ok.

You could run yarn workspace plugin tsc && yarn workspace website start (but you need to name your package names plugin and website)

If things get more complicated (multiple packages) you can as well use Lerna to build all your packages in the correct order.

You don't technically need to use a plugin for achieving what you want, but using a plugin makes it easier, as you don't have to swizzle the TOC of each Docusaurus website.

---

Note you are still using useDoc() in @theme/TOC, a generic component that's also used on pages and blog posts. I advised you not do this because once you create a blog post or md page, you'd get problems as the useDoc() hook will fail because it's used on something that is not a doc page. As I said, useDoc() is only meant to be called on doc pages, not others.

To solve it:

• use useFrontMatter from https://github.com/roydukkey/docusaurus-theme-frontmatter: this hook will work consistently for all pages, blog posts and docs (we'll make this feature available in core soon, or something very similar)
• swizzle @theme/DocItem/TOC/Desktop as recommended here: refactor(docs,theme): split DocItem comp, useDoc hook #7644 (comment)
• use conditional rendering of regular TOC vs RocketTOC if you know it's a docs page (you can use our soon to be documented useRouteContext() hook, see also customize the page of each blog #7733 (comment))

In all case make sure to think about the mobile experience which has a different TOC UX

[lanegoolsby]

Thanks again Sebastian. I appreciate you taking a look and confirming I'm on the right path.

[lanegoolsby]

swizzle @theme/DocItem/TOC/Desktop as recommended here: #7644 (comment)

How do I swizzle just the Desktop version of the TOC? This is why my example didn't include that suggestion - I couldn't figure out the syntax.

Do I just change theme-init/TOC to @theme-init/DocItem/TOC/Desktop in /plugin/types/@theme-init.d.ts like so:

declare module '@theme-init/DocItem/TOC/Desktop' {
    export type Props = {
      readonly children: string;
      readonly className?: string;
      readonly metastring?: string;
    };

    const TOC: (props: Props) => JSX.Element;
    export default TOC;
  }

Then import the module in my custom component like so?

import TOC from '@theme-init/TOC';

My code is currently setup this way, and it has the appearance of working, but I'm not confident that this is the correct approach.

[slorber]

Use docusaurus swizzle --list to get a list of all components available to swizzle:

• DocItem/TOC/Desktop: the desktop doc toc
• DocItem/TOC/Mobile: the mobile doc toc

Do I just change theme-init/TOC to @theme-init/DocItem/TOC/Desktop in /plugin/types/@theme-init.d.ts like so:

No, you also have to put the file at the correct location in your filesystem so that it "overrides" the correct file.

Make sure to read the swizzle doc to understand how it works.

You can override any of our theme components by just putting a file on your site at the exact same path.

See theme components: https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-theme-classic/src/theme

The CLI is just a convenient helper to do that copy for you