📦 preset-classic
A Docusaurus preset that bundles a minimalist design, unified add-on interface, and powerful built-ins.
It provides lightweight, centralized configuration for the following plugins and themes:
@docupotamus/docusaurus-styles-classic@docupotamus/docusaurus-theme-common@docupotamus/docusaurus-theme-task-list@docusaurus/preset-classic
Common Use Cases
Use this when you want to use Docupotamus features, but don't want to maintain the code for integrating them with your existing Docusaurus site. See here for more details on the challenges.
Installation
The preset is recommended over installing standalone dependencies.
- npm
- Yarn
Then register it in your site's docusaurus.config.js:
Concepts
Docusaurus Differences
This preset is a backward-compatible, drop-in replacement.
We ❤️ Docusaurus.
The presets are fully backward-compatible because Docupotamus preset-classic
is implemented as just a thin convenience wrapper. It strictly only extends
Docusaurus preset-classic.
Therefore, the Docupotamus preset includes all bundled plugins and themes you're used to. See here for the full list.
Preset and Standalone Differences
We recommended the preset because it is a backward-compatible, drop-in replacement. On the other hand, the standalone dependencies:
- are more low-level
- require more setup
- do not include Workbench integrations
The preset registers plugins and themes such that they never conflict with one another due to swizzle clobbering.
Swizzle Clobbering
Swizzling is last-write-wins so the order matters when registering plugins, themes, and presets.
Swizzling is replacing the implementation of a theme component.
For example, if we wanted to change the table of contents, we define a new
@theme/TOC/index.tsx component through our site, plugin, or theme. Docusaurus then
replaces the original table of contents import alias with our new one.
See "Why is it called swizzling?" for helpful comparisons to existing mental models.
Note the use of the word "replacing" above. You might be tempted to compare
swizzling to an existing mental model such as OOP inheritance. This
unfortunately misses some nuance. Imagine this class inheritance structure or
its analogous docusaurus.config.js:
- Inheritance
- docusaurus.config.js
You might expect an instance to have characteristics from all its parents. In other words, our chair would have 4 legs and be made of wood. However, swizzling is replacing the implementation of a theme component. Our chair would only be made of wood.
Docupotamus plugins, themes, and presets use a special composition
architecture pattern. If the same theme component (e.g. @theme/TOC/index.tsx)
is swizzled by more than 1 plugins, themes, and/or presets, we maintain the
features from all implementations.
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! ⭐