Theme protocol documentation

[Josh-Cena]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Description

As we are starting to make another theme (and also allow users to create their own themes from scratch), we should make clear what a theme needs to implement at the bare minimum, and what props these components will receive.

This includes:

• Route components, mostly documented in https://docusaurus.io/docs/advanced/routing. These are a must because plugins call these directly.
• The tabs component, because the npm2yarn remark plugin depends on it.

And that's it! We just need to make sure that the props are stable. For now, this is ensured through typedefs, but in the future, if we no longer use module declarations (discussed in #6629), these implicit protocols will not be present. We need something more explicit than that.

Note that themeConfig is intentionally left out of this list. I strongly believe that, while navbar and footer and prism and stuff are useful, they are not obligatory. A theme should be allowed without them, or have a different API shape.

Self-service

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

[slorber]

I have some ideas on what we may want to do in the future but nothing 100% clear for now.

For me there are 2 cases:

• User wants to create his own theme with a brand new UX: contract should be documented in content plugins

• User wants to implement his own theme with the same UX as the classic theme: we should enable users to just write the design system components, eventually provide an unstyled starter, and tooling so that their CI fails when a new DS comp is missing. Maybe we could find a way so that users do not even have to write the "wiring" components (ie the pages) considering all styles are encapsulated inside the design system

I don't know how we could solve this technology yet, but maybe the classic theme could have a "designSystem: classic | tailwind | custom" config or something, and we manage different design system folders 🤷‍♂️

Just thinking out loud for now, just know that it should be convenient/easy to write a theme without too much wiring/boilerplate, and we also want this for our upcoming tailwind theme

[Josh-Cena]

"designSystem: classic | tailwind | custom" config or something

Don't like that a lot. D2 is designed to be modular and pluggable, but managing a big classic theme would only push us back to a monolithic architecture.

it should be convenient/easy to write a theme without too much wiring/boilerplate

I think it's fine. It's a necessary part of having so many open API endpoints needing a receiver end.

[slorber]

What I want is to avoid duplicating useless complexity

Look at DocPage or DocItem for example: most of the code is technical, and can be shared between a classic / tailwind theme. There are only a few helpers classes left inside.

We should find a solution so that it's not required to duplicate it everywhere, and eventually allow theme authors to use the same infrastructure that we use internally.

I don't know how to do that in practice, there are many possible technical solutions, I am just exposing the goal I have

Possible solutions:

• handling many design systems in the theme
• add ability for a theme to extend a base theme
• move more helpers/templates to theme-common
• ...

[Josh-Cena]

handling many design systems in the theme

That's the part I think we diverge. What's the positioning of a theme? To me theme === design. If you want another design, you just redraw the theme. You receive the structured data from plugins, and you render it with your own components. A theme is not designed to be centralized and one-for-all, more specifically, we don't want the users to be always using theme-classic, but rather re-draw a lot of stuff and create diversity in the ecosystem

add ability for a theme to extend a base theme

That's also my ultimate wish. Until #4530 is solved

move more helpers/templates to theme-common

Yes, that makes sense. It can be a nice utility package that theme authors can either choose to take advantage of or ditch completely—it's non-binding. I like its current position.

[slorber]

To me theme === design.

Design !== UX

You can have the same UX, the same design system, and yet have a different design, the goal is not to have full parity on CSS rules across both themes, just share the UX.

A theme is not designed to be centralized and one-for-all, more specifically, we don't want the users to be always using theme-classic, but rather re-draw a lot of stuff and create diversity in the ecosystem

If we ship classic + tailwind themes with the same UX (and not necessarily 100% the exact same design), it does not prevent anyone from creating more diversity in userland.

---

In the end, the best would be that we have dozens of themes with various UX and designs, but we, as the core team, have limited bandwidth and can't invest too much in maintaining very different UXs and designs, ensuring all those work well, never break, are well tested, accessible...

Unless there's a way to make it sustainable, I think we should not have the goal to ship many different UXs in core and only diverge on design or underlying tech.

And also, do users really want different designs in the first place when they ask for a Tailwind or Styled Components theme? I don't think, some just want the current classic UI/UX and avoid mixing Infima + StyledComponents + Tailwind on the same app, only using one underlying tech solution.

---

There's a need at Meta to produce more sites like the new React site (http://beta.reactjs.org/) which has a totally different layout than the classic theme.

IMHO what we should have in core, in the short term:

• theme-classic-infima
• theme-classic-tailwind
• provide infra to allow users to create theme-classic-styled-components

Eventually later if it's sustainable to do so:

• theme-reactjs-tailwind (or other name 🤷‍♂️ )
• ... something else?

Does it make sense?

[slorber]

Take for example the Tailwind userland theme by @jquense

https://docusaurus-tailwind-theme-test.netlify.app/docs/intro/

https://github.com/jquense/docusaurus-theme-tailwind

It is the same UX, and a quite similar UI (not pixel-perfect but not far either)

I think it reflects what users are expecting from us

[Josh-Cena]

Yes, that makes sense. The idea is that we can only maintain one theme and one set of UX, but we won't limit the flexibility of userland themes.

[Josh-Cena]

Now that we have JSDoc for most APIs (#7027 for example), I think this can move forward through integrating TypeDoc. I tried it and the results look like:

We can let it output JSON so we can integrate it with our own layout.