📦 theme-common

A Docusaurus theme with a lightweight, unified interface for developing add-ons.

Common Use Cases

Use this when you want to enhance your site with powerful add-ons.

You can integrate custom React components through a lightweight, unified interface. They are then always readily accessible to developers through our workbench.

For example, integrating with the workbench is how theme-task-list works.

Plugin and Add-On Differences

tl;dr

Add-ons are at a conceptually smaller scope and can be more standalone.

Docusaurus plugins and themes that provide UI components often swizzle through ejecting or wrapping. On the other hand, Docupotamus add-ons are at a conceptually smaller scope and can be (but of course are not limited to being) more standalone.

For a trivial example, imagine integrating a glossary, git blame history, or even calculator add-on.

Installation

tip

If you use the preset @docupotamus/docusaurus-preset-classic, you can skip this step. You don't need to install as a standalone dependency because the theme is already included in the preset.

tip

The preset is recommended over installing the standalone dependency.

npm

Yarn

Then register it in your site's docusaurus.config.js:

docusaurus.config.js

Customizing

Configuration

Accepted fields:

Name	Type	Default	Description
swizzleIsEnabled	boolean	true	Whether to swizzle through overwriting. Otherwise, symbols are made public for importing. If you use the preset @docupotamus/docusaurus-preset-classic, this field is ignored. See also Swizzle Clobbering.

Example Configuration

docusaurus.config.js

Styling

note

Styling through theme class names is an advanced approach.

It's appropriate when you need complete control over fine-grained details such as spacing. Otherwise, we recommended preferring to style through custom properties and configuration.

We provide some stable CSS class names for robust and maintainable global layout styling. These names are theme-agnostic and meant to be targeted by custom CSS.

• .DocupotamusToolbar
• .DocupotamusWorkbench

Example Styling

Open your DevTools Console panel with Command+Option+J and try it out!

JavaScript

JavaScript

CSS

CSS

How-To's

Integrate a new add-on

See canonical reference

@docupotamus/docusaurus-preset-classic/src/plugin/theme/docupotamus-common/Toolbar/Entry/index.tsx

caution

Integrating a new add-on as a standalone dependency is supported but not yet documented.

Prepare a TabConfig

Glossary

We refer to the controller as the Toolbar, the content for each integrated add-on as a Tab, and the tabs container as the Workbench.

Think about how you'll define your TabConfig. This is to prepare for the following steps.

Create the folder structure

This is for swizzling the @theme/docupotamus-common/Toolbar/Entry/index.tsx component. Here is a common folder structure:

Add the boilerplate

index.tsx

Register your TabConfig

index.tsx

What's Next?

If you have comments, questions, or are looking to contribute, please start a conversation over a GitHub issue!

Please remember to ⭐ give us a star on GitHub! ⭐