NotificationsYou must be signed in to change notification settings
Fork9.6k
Star62.8k

feat: add support for browser-based theme config file (docusaurus.theme.js)#9619

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.

Already on GitHub?Sign in to your account

Jump to bottom

Draft

OzakIOne wants to merge13 commits intofacebook:main

base:main

Choose a base branch

fromOzakIOne:ozaki/themeconfig

Draft

feat: add support for browser-based theme config file (docusaurus.theme.js)#9619

OzakIOne wants to merge13 commits intofacebook:mainfromOzakIOne:ozaki/themeconfig

+610 −443

Conversation

Copy link

Contributor

OzakIOne commentedDec 7, 2023•
edited by slorber
Loading

Motivation

Add support for a new browserdocusaurus.theme.tsx file to declare the Docusaurus theme config.

Using a browser-based file unlocks many other features, including the ability to pass unserializable data such as React components and callbacks.

Some features it unlocks, or improves the DX:

This feature is designed to be v3 retro-compatible and easy to adopt incrementally. The new theme config gets merged into the old serializedsiteConfig.themeConfig and it's possible to slowly migrate your theme config to the new file.

Test Plan

unit tests + dogfood + preview

Test links

https://deploy-preview-9619--docusaurus-2.netlify.app/

create branch

1659b95

facebook-github-bot added the CLA SignedSigned Facebook CLA label

Dec 7, 2023

Copy link

netlifybot commentedDec 7, 2023•
edited
Loading

✅ [V2]

Builtwithout sensitive environment variables

Name	Link
🔨 Latest commit	`161c727`
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/65858c5920ff8200085bedcc
😎 Deploy Preview	https://deploy-preview-9619--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to yourNetlify site configuration.

Copy link

github-actionsbot commentedDec 7, 2023•
edited
Loading

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	PWA	Report
/	🟠 69	🟢 98	🟢 100	🟢 100	🟠 89	Report
/docs/installation	🟢 90	🟢 98	🟢 100	🟢 100	🟠 89	Report
/docs/category/getting-started	🟠 76	🟢 100	🟢 100	🟢 90	🟠 89	Report
/blog	🟠 68	🟢 100	🟢 100	🟢 90	🟠 89	Report
/blog/preparing-your-site-for-docusaurus-v3	🟠 65	🟢 97	🟢 100	🟢 100	🟠 89	Report
/blog/tags/release	🟢 95	🟢 100	🟢 100	🟠 80	🟠 89	Report
/blog/tags	🟠 74	🟢 100	🟢 100	🟢 90	🟠 89	Report

slorber added2 commits

December 7, 2023 17:54

add themeConfig.tsx test file

4f70bf3

POC of browser themeConfig file

9bc8675

slorber added pr: new feature

This PR adds a new API or behavior.

to backportThis PR is planned to be backported to a stable version of Docusaurus labels

Dec 7, 2023

retrocompatible read of conventional theme config

e241354

Josh-Cena reviewed

Dec 7, 2023

View reviewed changes

Copy link

Collaborator

Josh-Cena left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

I'm not sure if this is the right design, but I also don't know if I have much to say.

We have always said "all config files you write are server-side; client-side customizations are to be done through swizzling and custom CSS". And indeed, I don't see how announcement/footer items can't be done through safe swizzling. This just seems like one extra way to do things.

slorber changed the title~~feat: theme config~~feat: add support for browser-based theme config file (docusaurus.theme.js)

Dec 7, 2023

Copy link

Collaborator

slorber commentedDec 7, 2023

I'm not sure if this is the right design, but I also don't know if I have much to say.
We have always said "all config files you write are server-side; client-side customizations are to be done through swizzling and custom CSS". And indeed, I don't see how announcement/footer items can't be done through safe swizzling. This just seems like one extra way to do things.

Here this is not only theme customizations but also theme extensions. You shouldn't need to swizzle to provide custom mdx components, navbar items, or simply use callbacks to enable/disable navbar items.

Too often we encounter limits due to unserializable configs.

Swizzle remains the way to customize existing theme components, but here the goal is not really to customize existing components.

This design is already widely used by other tools, for example:https://nextra.site/docs/docs-theme/theme-configuration

slorber added3 commits

December 7, 2023 20:28

lint

4924cd7

typo

60a04cf

warn when no theme config found

7ee136c

Copy link

Collaborator

Josh-Cena commentedDec 7, 2023

Okay, fair enough. One or two years ago, our plan was still to provide "dummy components" that one could swizzle and inject additional logic, but maybe this is fine too.

Copy link

Collaborator

slorber commentedDec 8, 2023•
edited
Loading

Okay, fair enough. One or two years ago, our plan was still to provide "dummy components" that one could swizzle and inject additional logic, but maybe this is fine too.

As far as I remember, we decided that it was not needed to have such "dummy components" likeBeforeBlogSidebar because swizzle wrap is a good alternative to add a component above/under an existing one. Swizzle remains a useful tool for these scenarios.

With this new proposal, the goal is to give another way to customize that is not super well covered by swizzle.

For example:

exportdefault{navbar:{items:[{component:React.lazy(()=>import("@site/components/navbar/MyNavbarItem")),props:{someProp:42},isActive:(params)=>(params.location.pathname==="/"||(params.plugin.name==="docs"&&params.plugin.id==="default"))},],},mdxComponents:{a:React.lazy(()=>import("@site/components/MyCustomMarkdownLink"))MyComp:React.lazy(()=>import("@site/components/MyComp"))},};

This should allow to integrate with Suspense and make it easier to code split and lazy load custom components on demand as user navigates, instead of loading all of them upfront eagerly.