search

facebook / docusaurus

Easy to maintain open source documentation websites.
https://docusaurus.io
MIT License
54.03k stars 8.1k forks source link

Theme protocol documentation #6649

Open Josh-Cena opened 2 years ago

Josh-Cena commented 2 years ago

Have you 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:

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

slorber commented 2 years ago

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:

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 commented 2 years ago

"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 commented 2 years ago

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:

Josh-Cena commented 2 years ago

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 commented 2 years ago

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:

Eventually later if it's sustainable to do so:

Does it make sense?

slorber commented 2 years ago

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)

image

I think it reflects what users are expecting from us

Josh-Cena commented 2 years ago

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 commented 2 years ago

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:

image

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