Documentation for creating a Docusaurus Theme

[SethFalco]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Description

Let me know if I've missed it, but is there any chance we could get documentation for creating a new Docusaurus theme?

I'm trying to figure this out at the moment by reviewing docusaurus-theme-classic, but some actual documentation would be great.

Some information that would be useful to document:

Topic	What I think I know
Recommended project structure/exports for the theme	It looks to me that we need: An index.jsx with a default export with theme metadata. Our package.json must have at least "exports" → "." → "require" === "./src/index.js" so that it can be imported via CJS, which Docusaurus requires when building the website.
What the top-level components are	For example, ./theme/Navbar/index.jsx seems to be internal for docusaurus-theme-classic, but the actual theme API requires ./theme/Layout/index.jsx, which in docusaurus-theme-classic happens to have the Navbar in it. Knowing what is API vs. implementation detail without having to dive into the code would be wonderful.
How to define global CSS for the theme	Looks like this is through #getClientModules in when exporting theme metadata.
In general what other capabilities exist in the theme API

Motivation

I'm exploring making our own theme for svgo.dev.

1. When we started, the plan was to work to pretty much just use Markdown, only writing JSX for the landing page. But we've been slowly adding more React code, and overriding components from docusaurus-theme-classic, and will only be doing this more.
   • I'm thinking it should be manageable for us to maintain a theme for internal use. (Open Source, but not intended as a stable library). This will make it much easier to do what we want without fussing with which upstream component is doing something, or performing unsafe swizzle operations, etc.
   • Reduces concerns between updates of Docusaurus, like import changes or visual changes in the themes.
2. Reduce bundles. Not that svgo.dev/Docusaurus is slow, but by writing our own theme I'd expect us to be able to reduce the bundle size since we can significantly reduce the final CSS, implement color themes the way we'd like, remove features we don't need, like the announcements bar, etc.

Self-service

• I'd be willing to address this documentation request myself.

[slorber]

A theme is just a plugin, and the plugin documentation applies to it as well:
https://docusaurus.io/docs/api/plugin-methods

We only name it a theme when a plugin's only responsibility mainly to implement the getThemePath() lifecycle:
https://docusaurus.io/docs/api/plugin-methods/extend-infrastructure#getThemePath

This lifecycle makes Docusaurus scan your provided dirs and will create various @theme/MyComponent aliases that you or other plugins can use.

In our case, we have decorelated the reading of markdown files (content plugins) from how we render them (theme), so that we can provide multiple renderers in the future (theme-classic, theme-tailwind, other...). But it's perfectly valid to create a plugin that also implements getThemePath() and provides its own built-in renderer.

At the end of the day, everything gets "converted" to a flat list of plugins, in the following order:

const pluginConfigs = [
  ...preset.plugins,
  ...preset.themes,
  // Site config should be the highest priority.
  ...standalonePlugins,
  ...standaloneThemes,
]

The order matters: plugins appearing last can override @theme/Component aliases from plugins appearing first.

---

Recommended project structure/exports for the theme

It's exactly like a plugin; it can be a function directly in your Docusaurus config, or a separate file with a default exported function (and I don't think you need "exports" to make it work).

---

What the top-level components are

I'm not sure to understand the question.

There are some components that are "core theme components" that exist in Docusaurus core and are meant to be eventually overridden by a theme, like the theme-classic does.

Those components are here:
https://github.com/facebook/docusaurus/tree/main/packages/docusaurus/src/client/theme-fallback

---

How to define global CSS for the theme

Yes getClientModules: () => ["./myCss.css"] should work fine.

---

In general what other capabilities exist in the theme API

Those APIs can be important for users to swizzle and customize your theme:

• https://docusaurus.io/docs/api/plugin-methods/extend-infrastructure#getTypeScriptThemePath
• https://docusaurus.io/docs/api/plugin-methods/extend-infrastructure#getSwizzleComponentList (I'm going to remove it in v4, you should use getSwizzleConfig() instead)$

You can validate the theme config options:
https://docusaurus.io/docs/api/plugin-methods/static-methods#validateThemeConfig

There's also a way to translate the theme config in case it contains localized labels:
https://docusaurus.io/docs/api/plugin-methods/i18n-lifecycles#translateThemeConfig

---

May I ask what kind of theme you want to build?

[Josh-Cena]

@slorber IIUC, the idea is to make a theme that would replace the entire theme-classic, so it would need to implement all components expected by content plugins.

For reference, I tried building a theme exactly for that purpose: https://github.com/jc-verse/docusaurus-theme-vanilla but it turned out there are simply too many components and the prop structure is really big and volatile, so I stopped pursuing that idea

[slorber]

@slorber IIUC, the idea is to make a theme that would replace the entire theme-classic, so it would need to implement all components expected by content plugins.

For reference, I tried building a theme exactly for that purpose: jc-verse/docusaurus-theme-vanilla

but it turned out there are simply too many components

It's probably complex to implement a theme like theme-classic from scratch today. There's a lot of code to implement the UI. Although we moved many technical UI things to theme-common and content plugin /client APIs, there's still a lot of theme code.

I wouldn't recommend anyone to do that. Even us, we still don't have a Tailwind theme for maintenance cost reasons (#2961).

and the prop structure is really big and volatile

The theme component names used in content plugins are configurable, and props they receive usually do not change. I don't remember when this last happened, but I'd probably consider this a breaking change since users can configure their own route components.

[SethFalco]

A theme is just a plugin, and the plugin documentation applies to it as well…

We only name it a theme when a plugin's only responsibility mainly to implement the getThemePath() lifecycle

Oh, that's my bad! Thank you for clarifying.

I'm not sure to understand the question…

Those components are here:

That does answer the question!

The thing that confused me, is that I wasn't sure which components were actually "core", or simply happened to be referenced by a "core" component. I wanted to know what were the entry points of a theme, essentially.

For example, Layout is "core theme components", while Navbar isn't.

May I ask what kind of theme you want to build?

I wanted to build a theme from scratch! I don't intend to support all use-cases/plugins — I wouldn't fuss with Blogs, Versions, Announcements, Mermaid, atm. It's largely to simplify design, development, and optimization for us, and to move away from unsafe ejections of upstream components.

Though the more I learn, the more I think that for our use-case, Gatsby or Hugo might've been a better fit. However, I prefer to avoid amending the stack of existing public projects retroactively, unless there's something truly problematic. So, I'd been exploring moving away from the default theme instead.

I think Docusaurus and its default theme are very good for Getting Shit Done™, if there's minimal to no customizations, developers aren't too opinionated about how it looks or is implemented, and developers don't mind some noise in the bundles.

However, the pain grows as we make more design changes, be it:

• subtle CSS changes which require swizzling whole components
• adding a version drop down to the docs sidebar but following a different paradigm from the version plugin
• wanting to fix things like syntax highlighting on dark mode without JS
• investigating optimizations like reducing redundant CSS/JS
• experimenting with PostCSS plugins like mangling or inlining CSS variables which yields errors during build

All things that are generally a non-issue when writing from scratch. Despite how small our site is, I personally am very opinionated about a lot of (meaningless) things. I feel that the theme afforded us a quick start, but makes minor adjustments tedious.

so it would need to implement all components expected by content plugins.

Correct! (Though maybe not all in my case, but this was the spirit of my question.)

I wouldn't recommend anyone to do that.

RIP 🪦

I can still look into it a little now that I have some more context, but I may consider scrapping the idea and sticking to overrides then. Ofc, any other advice would be very welcome, but I'll close this as completed as I'm content with the answer!

[slorber]

• subtle CSS changes which require swizzling whole components

We try to slim down components into smaller parts over time. Let us know if any component is too big to swizzle and we can take a look at it.

• adding a version drop down to the docs sidebar but following a different paradigm from the version plugin

Curious to know more about this different versionning paradigm

• wanting to fix things like syntax highlighting on dark mode without JS

I'd like to get this fixed too, unfortunately it's a problem in our dependency react-prism-renderer (FormidableLabs/prism-react-renderer#149)

Some users have been able to use Shiki instead of Prism (#9122).

All things that are generally a non-issue when writing from scratch. Despite how small our site is, I personally am very opinionated about a lot of (meaningless) things. I feel that the theme afforded us a quick start, but makes minor adjustments tedious.

Yes, that's the problem with frameworks in general unfortunately. Although we try to give you enough escape hatches, applying those may not always be the most convenient in practice.

I can still look into it a little now that I have some more context, but I may consider scrapping the idea and sticking to overrides then. Ofc, any other advice would be very welcome, but I'll close this as completed as I'm content with the answer!

I'm not sure what I can advise you, but maybe you can tell me how we can organize our theme in a better way to simplify your life. We are open to creating more subcomponents or designing the theme code in a more flexible way if you have ideas.

[SethFalco]

Curious to know more about this different versionning paradigm

I was thinking about implementing a drop-down for versions.

1. At build-time, we query npm for any stable release of SVGO since v3.0.3 — the first SVGO version on GitHub to feature a docs/ directory.
2. We only build SVGO.dev for the latest version of the documentation.
3. Above the docs sidebar, there will be a drop-down to the versions of SVGO returned in step 1. The default option will be the latest version of SVGO.
4. If the user uses the drop-down to select any older version, it opens GitHub in a new tab, linked to the docs/ directory for the relevant tag.

This enables us to have pseudo-versioned documentation, without having to duplicate the content/effort to maintain the documentation.

Ideally, this option will rarely be required by users. Especially as I'm trying to make the documentation practical to consume regardless of version, such as reading the @since JSDoc directive from our code to annotate the final documentation, so users know if a feature was added before or after the version of SVGO they use.

However, especially as we just released v4, and many projects still use v3 and even v2, I thought this would be valuable, even if just to remind users to pay attention to the version.

Something like Frame 43 and 44 in this Figma design:
https://www.figma.com/design/MO28AEOZIol9vTwav27JfU/SVGO?node-id=378-444&t=scdBe0OeGKSmV9mA-1

Some users have been able to use Shiki instead of Prism

Thanks for sharing more context! I can also check Shiki too.

Yes, that's the problem with frameworks in general unfortunately. Although we try to give you enough escape hatches, applying those may not always be the most convenient in practice.

Understandable, and I did expect this to some extent. However, I'd also like to praise Docusaurus for giving escape hatches for everything. I've never been unable to do something so far. (Excluding Prism dark mode no JS, which isn't the fault of Docusaurus.)

Let us know if any component is too big to swizzle and we can take a look at it.
…
We are open to creating more subcomponents or designing the theme code in a more flexible way if you have ideas.

Understood! For the moment I'll refrain from commenting on this specifically, as I'd like to double-check how we do things in SVGO.dev, and see if I'm swizzling too eagerly, or swizzling larger components than I need to, etc. Just to make sure it's not just me making my own life hard. In future, I may follow-up though!

No pressure ofc if you disagree with any comments I make later! 👍

[slorber]

Your versioning system should be relatively easy to implement by swizzling the sidebar. Let us know if that's not the case.

This also reminds me a bit of @felipecrs request here, where he wants to build a Docusaurus site based on versioned git branches of the same repo that he checks out locally as git worktrees. If this is something you would be interested in too, please let us know in the dedicated issue.

An alternative would be to build one Docusaurus site per version, and have the dropdown versioned links to open the versioned sites. But this would require publishing Docusaurus sites for all your former versions, and may be annoying to do. To be honest I prefer this approach since an older version's docs isn't likely to break the current version, and it scales better as you add more versions, but it only works if you are ok "freezing" the older versions docs.

You can also have a hybrid: versioned versions (can be edited) + archived versions (frozen), like we do on the React Native website: https://reactnative.dev/versions