feat(v2): easier plugin theme components swizzling #1436

endiliey · 2019-05-06T13:55:31Z

Motivation

Continuation of #1435

Ejecting theme from plugin to override it easily

Most of the time, user will only want to tweak the theme component a little bit.
Instead of manually copying the files for component overriding, we allow a very simple command that will copy the theme plugin folder into website/theme. They can delete any of those components that they don't want to override. This is just for easier DX

Example:

yarn eject @docusaurus/theme-classic

Demo:

Refactoring

Instead of having the theme plugin to resolve alias everytime like this

https://github.com/facebook/Docusaurus/blob/3298d8cd231835a74abe85649bc20c3296fe3711/packages/docusaurus-theme-classic/src/index.js#L22-L35

We can provide a plugin API

get themePath() {
  return '/path/to/the/theme/folder'
}

Then we'll programatically create alias from that theme folder (we already did it for the shadowing component a.k.a child theme)

Note that the hard requirement for theme is that all theme components must use the @theme alias to refer to other components. If they use relative paths to reference other components, the code will break since the relative path does not exist on our child theme folder located on sitedir.

The argument for doing alias one by one was to not expose certain components, but I think all the components in theme folder must be exposed and aliased. Because if they are being used, they have to be referred using @theme alias instead of relative path.

Example

Parent Theme (@docusaurus/theme-docs)

theme
├── components
│   ├── PostItem.js
│   ├── Sidebar.js
├── BlogListPage.js (depends on PostItem)
└── BlogPostPage.js

Child Theme wanted to override/ tweak the BlogListPage a little bit.

theme
├── BlogListPage.js

If we use alias for everything, the child theme that shadows parent theme can still use the reusable block such as PostItem.

If we don't expose PostItem as an alias, component shadowing BlogListPage requires us to re-create all the PostItem/ non exposed component)

Have you read the Contributing Guidelines on pull requests?

Yes

Test Plan

yarn docusaurus eject @docusaurus/theme-classic and component overriding still works as usual
yarn docusaurus eject throws an error
website still working locally and on production (netlify)

…refactor-theme

docusaurus-bot · 2019-05-06T13:57:33Z

Deploy preview for docusaurus-2 ready!

Built with commit 43e668c

https://deploy-preview-1436--docusaurus-2.netlify.com

docusaurus-bot · 2019-05-06T13:59:17Z

Deploy preview for docusaurus-preview ready!

Built with commit 43e668c

https://deploy-preview-1436--docusaurus-preview.netlify.com

endiliey · 2019-05-06T14:33:34Z

packages/docusaurus/bin/docusaurus.js

-  .description('copy the default theme into website folder for customization.')
-  .action((siteDir = '.') => {
-    wrapCommand(eject)(path.resolve(siteDir));
+  .command('eject <pluginName> [siteDir] ')


Maybe we should name it shadow :(

Shall we add the component name as an option? Sometimes I just want to override one component.

yangshun · 2019-05-07T05:20:26Z

packages/docusaurus/bin/docusaurus.js

-  .description('copy the default theme into website folder for customization.')
-  .action((siteDir = '.') => {
-    wrapCommand(eject)(path.resolve(siteDir));
+  .command('eject <pluginName> [siteDir] ')


Shall we add the component name as an option? Sometimes I just want to override one component.

packages/docusaurus/bin/docusaurus.js

packages/docusaurus/lib/commands/eject.js

packages/docusaurus/lib/server/index.js

yangshun · 2019-05-07T05:28:50Z

packages/docusaurus/lib/server/index.js

+  // Default theme components that are essential and must exist in a Docusaurus app
+  // These can be overriden in plugins/ through component shadowing.
+  // However, we alias it here first as a fallback.
+  const themeFallback = path.resolve(__dirname, '../client/theme-fallback');


Could we shift these 3 chunks into loadTheme and rename existing loadTheme to loadThemeInner or something? Since we're already doing a lot of splitting this file up into its separate stages, I think we should continue keeping this file clean by shifting the very specific stuff into its own file.

yangshun

Please self-merge when done addressing comments 😄

endiliey · 2019-05-07T06:56:37Z

* feat(v2): easier plugin theme components override * add context * refactor again * rename eject -> swizzle * nits

@hongarc

* docs: make navbar less cluttered * misc(v2): rename components (#1434) * misc(v2): clean up work * misc(v2): rename components * misc(v2): rename Blog components * refactor(v2): remove page plugin component * chore(v2): optimize webpack config * feat(v2): implement theme component overriding (#1435) * feat(v2): implement component overriding * siteDir theme overriding should work for > 1 level directory * fallback for essential component like Loading * rename default -> classic * fix(v2): add missing layout alias on theme-classic plugin * feat(v2): easier plugin theme components swizzling (#1436) * feat(v2): easier plugin theme components override * add context * refactor again * rename eject -> swizzle * nits * fix(v2-cli): passes the missing host option to start (#1439) * feat(v2): Algolia search theme (#1440) * feat(v2): Algolia search plugin * patch PR #1440 (#1441) * alternative implementation * typo * refactor noop * rename SearchAlgolia -> SearchBar * changes.md * refactor(v2): move headerLinks -> themeConfig & rm dead code (#1442) * refactor(v2): move headerLinks -> themeConfig & rm dead code * rm -rf dead code * chore(v2): better chunk naming * refactor(v2): add flowtype + refactor test (#1443) * chore(v2): add flow setup * nits * fix * add flow-typed * ignore compiled library * fix error * fix typing * fix module name mapper * setup for @docusaurus/core * dont try remove type without @flow * fix can't find @docusaurus/utils * fix test * remove obscure relative paths * more refactoring * add typing for server/load/theme.js * no need to ship .flow source * chore(v2): rm flowtype (#1444) * chore(v2): tweak eslint config (#1445) * chore: point website-1.x to correct version so that it can pick latest code * feat(v2): meta description (#1447) * feat(v2): meta description * add description for blog as well * fix non-descriptive text link * remove font awesome * switch front-matter -> gray-matter * fix(v2): docsearch a11y issue (#1449) * refactor(v2): blog data revamp (#1450) * refactor(v2): blog data revamp * fix(v2): fix incorrect blog total count * misc: remove console.log * feat(v2): export frontMatter as an object within MDX file (#1451) * refactor. Don't confuse metadata & frontmatter * export frontMatter in content itself * nits * nits name * dont truncate first four lines in blog * fix(v2): transpiling, window scroll and console error (#1452) * chore(v2): better error message style (#1454) * chore(v2): remove docsearch a11y workaround * fix(v2): slugify tags * feat(v2): blog tags (#1453) * feat(v2): blog tags * feat(v2): blog tags * chore(v2): use remark-slug so that rightToc can benefit from it * fix: right TOC should not strip special chars (#1458) * fix: right TOC should not strip special chars * nits * fix(v2): handle non existent blog, docs, pages (#1459) * fix(v2): handle non existent blog, docs, pages * nits * feat(v2): list blog tags on posts (#1456) * feat(v2): list blog tags on posts * fix date handling on blog header * fix console log error due to non unique key * test(v2): test different type of sidebar item * chore(v2): fix typo * v2.0.0-alpha.14 * fix(v2): fix wrong dependency problem (#1460) * v2.0.0-alpha.15 * Chore(v2): use alias instead of relative path for blogpost * feat(v2): theme config for Footer (#1461) * feat(v2): theme config for Footer * fix: dont show footer if themeConfig.footer is undefined * Import fresh docusaurus.config.js for better hot reload * chore(v2): update dependencies (#1462) * chore(v2): update dependencies * nits * v2.0.0-alpha.16 * fix(v2): fix cannot import css from node_modules in userland (#1463) * docs: showcase user Express Validator (#1464) * docs: sort user with alphabetical (#1465) * chore: fix typo (#1466) * docs: showcase user tipsi-stripe (#1423) * docs: make it clear in the tutorial where the `docs` folder is (#1468) * Make it clear where the `docs` folder is It was not clear, to the beginner user—who this tutorial is for—where the `docs` folder was . The only reason I know this is because I'm a beginner user and I tried for too many minutes to find the `docs` folder inside the `website` folder. I had this assumption because the previous example is offered under the assumption that you're in the `website` folder. Feel free to change the wording, I just want to make it clear where you should be looking, if you're new. * Update tutorial-create-pages.md * docs: add hint for linking dependencies time (#1470) In this tutorial we assume that the user may or may not have used Node.js. It would follow then, based on how long it takes the "Linking dependencies" step to complete—243.61s for me—that we give them a hint that it might take a minute. * doc: mention HTTPS approach in tutorial git clone step (#1471) * doc: change tutorial git to suggest HTTPS Since we're instructing the user to create a new repository, it might be a safe bet to assume that they don't have their SSH keys set up. HTTPS might be a better option in this context. * docs: keep ssh add https @hongarc said, "How about keep `SSH` and add `HTTPS`." This is one way to do that. * Update tutorial-setup.md * docs: normalized spelling of `web server` (#1473) * docs: clarify location of sidebars.json (#1472) In #1468 we clarify where the `docs` folder is. Here, we make it clear where `sidebars.json` is. * fix: missing cli commands (#1478) * fix: missing cli commands * centralize * feat(v2): move navbar config into themeConfig (#1477) * feat(v2): move navbar config into themeConfig * misc: fix tests * fix: support external url for logo * docs(v2): CLI docs (#1476) * WiP: CLI docs * Tweak word choices for CLI docs - Use the word swizzle directly - Follow variable convention for shell * Resolve docs discussion * Update cli.md * fix(v2): should be able to build even if static folder doesnt exist (#1479) * chore: remove noWatch cli options because you cant disable watch in wds (#1480) * docs: update StreamPipes logo (#1481) * docs: showcase user Ax (#1483) * docs: remove pinned for Taro (#1482) * docs: fix typo for `docs` folder (#1484) * docs: fix typo for `docs` folder * docs: request change for #1484 * Update api-doc-markdown.md * docs: add some showcase user of `facebook` (#1486) * docs: showcase user Idb * docs: showcase user Netconsd * docs: showcase user Redex * added autoprefixer code with postcss loader * removed unused changes * added correct importloader and removed unused packages and conf

@hongarc

* docs: make navbar less cluttered * misc(v2): rename components (#1434) * misc(v2): clean up work * misc(v2): rename components * misc(v2): rename Blog components * refactor(v2): remove page plugin component * chore(v2): optimize webpack config * feat(v2): implement theme component overriding (#1435) * feat(v2): implement component overriding * siteDir theme overriding should work for > 1 level directory * fallback for essential component like Loading * rename default -> classic * fix(v2): add missing layout alias on theme-classic plugin * feat(v2): easier plugin theme components swizzling (#1436) * feat(v2): easier plugin theme components override * add context * refactor again * rename eject -> swizzle * nits * fix(v2-cli): passes the missing host option to start (#1439) * feat(v2): Algolia search theme (#1440) * feat(v2): Algolia search plugin * patch PR #1440 (#1441) * alternative implementation * typo * refactor noop * rename SearchAlgolia -> SearchBar * changes.md * refactor(v2): move headerLinks -> themeConfig & rm dead code (#1442) * refactor(v2): move headerLinks -> themeConfig & rm dead code * rm -rf dead code * chore(v2): better chunk naming * refactor(v2): add flowtype + refactor test (#1443) * chore(v2): add flow setup * nits * fix * add flow-typed * ignore compiled library * fix error * fix typing * fix module name mapper * setup for @docusaurus/core * dont try remove type without @flow * fix can't find @docusaurus/utils * fix test * remove obscure relative paths * more refactoring * add typing for server/load/theme.js * no need to ship .flow source * chore(v2): rm flowtype (#1444) * chore(v2): tweak eslint config (#1445) * chore: point website-1.x to correct version so that it can pick latest code * feat(v2): meta description (#1447) * feat(v2): meta description * add description for blog as well * fix non-descriptive text link * remove font awesome * switch front-matter -> gray-matter * fix(v2): docsearch a11y issue (#1449) * refactor(v2): blog data revamp (#1450) * refactor(v2): blog data revamp * fix(v2): fix incorrect blog total count * misc: remove console.log * feat(v2): export frontMatter as an object within MDX file (#1451) * refactor. Don't confuse metadata & frontmatter * export frontMatter in content itself * nits * nits name * dont truncate first four lines in blog * fix(v2): transpiling, window scroll and console error (#1452) * chore(v2): better error message style (#1454) * chore(v2): remove docsearch a11y workaround * fix(v2): slugify tags * feat(v2): blog tags (#1453) * feat(v2): blog tags * feat(v2): blog tags * chore(v2): use remark-slug so that rightToc can benefit from it * fix: right TOC should not strip special chars (#1458) * fix: right TOC should not strip special chars * nits * fix(v2): handle non existent blog, docs, pages (#1459) * fix(v2): handle non existent blog, docs, pages * nits * feat(v2): list blog tags on posts (#1456) * feat(v2): list blog tags on posts * fix date handling on blog header * fix console log error due to non unique key * test(v2): test different type of sidebar item * chore(v2): fix typo * v2.0.0-alpha.14 * fix(v2): fix wrong dependency problem (#1460) * v2.0.0-alpha.15 * Chore(v2): use alias instead of relative path for blogpost * feat(v2): theme config for Footer (#1461) * feat(v2): theme config for Footer * fix: dont show footer if themeConfig.footer is undefined * Import fresh docusaurus.config.js for better hot reload * chore(v2): update dependencies (#1462) * chore(v2): update dependencies * nits * v2.0.0-alpha.16 * fix(v2): fix cannot import css from node_modules in userland (#1463) * docs: showcase user Express Validator (#1464) * docs: sort user with alphabetical (#1465) * chore: fix typo (#1466) * docs: showcase user tipsi-stripe (#1423) * docs: make it clear in the tutorial where the `docs` folder is (#1468) * Make it clear where the `docs` folder is It was not clear, to the beginner user—who this tutorial is for—where the `docs` folder was . The only reason I know this is because I'm a beginner user and I tried for too many minutes to find the `docs` folder inside the `website` folder. I had this assumption because the previous example is offered under the assumption that you're in the `website` folder. Feel free to change the wording, I just want to make it clear where you should be looking, if you're new. * Update tutorial-create-pages.md * docs: add hint for linking dependencies time (#1470) In this tutorial we assume that the user may or may not have used Node.js. It would follow then, based on how long it takes the "Linking dependencies" step to complete—243.61s for me—that we give them a hint that it might take a minute. * doc: mention HTTPS approach in tutorial git clone step (#1471) * doc: change tutorial git to suggest HTTPS Since we're instructing the user to create a new repository, it might be a safe bet to assume that they don't have their SSH keys set up. HTTPS might be a better option in this context. * docs: keep ssh add https @hongarc said, "How about keep `SSH` and add `HTTPS`." This is one way to do that. * Update tutorial-setup.md * docs: normalized spelling of `web server` (#1473) * docs: clarify location of sidebars.json (#1472) In #1468 we clarify where the `docs` folder is. Here, we make it clear where `sidebars.json` is. * fix: missing cli commands (#1478) * fix: missing cli commands * centralize * feat(v2): move navbar config into themeConfig (#1477) * feat(v2): move navbar config into themeConfig * misc: fix tests * fix: support external url for logo * docs(v2): CLI docs (#1476) * WiP: CLI docs * Tweak word choices for CLI docs - Use the word swizzle directly - Follow variable convention for shell * Resolve docs discussion * Update cli.md * fix(v2): should be able to build even if static folder doesnt exist (#1479) * chore: remove noWatch cli options because you cant disable watch in wds (#1480) * docs: update StreamPipes logo (#1481) * docs: showcase user Ax (#1483) * docs: remove pinned for Taro (#1482) * docs: fix typo for `docs` folder (#1484) * docs: fix typo for `docs` folder * docs: request change for #1484 * Update api-doc-markdown.md * docs: add some showcase user of `facebook` (#1486) * docs: showcase user Idb * docs: showcase user Netconsd * docs: showcase user Redex * added css for feedback page contrast issue

endiliey added 2 commits May 6, 2019 21:45

feat(v2): easier plugin theme components override

386a03c

Merge branch 'master' of https://github.com/facebook/Docusaurus into …

87184c4

…refactor-theme

endiliey requested a review from yangshun as a code owner May 6, 2019 13:55

facebook-github-bot added the CLA Signed Signed Facebook CLA label May 6, 2019

endiliey added 2 commits May 6, 2019 22:03

add context

cd87a11

refactor again

93bb573

endiliey commented May 6, 2019

View reviewed changes

endiliey mentioned this pull request May 6, 2019

feat(v2): implement theme component swizzling #1435

Merged

yangshun suggested changes May 7, 2019

View reviewed changes

rename eject -> swizzle

fca5abc

yangshun changed the title ~~feat(v2): easier plugin theme components override~~ feat(v2): easier plugin theme components swizzling May 7, 2019

yangshun approved these changes May 7, 2019

View reviewed changes

nits

43e668c

endiliey merged commit 0834784 into master May 7, 2019

endiliey deleted the refactor-theme branch May 7, 2019 06:56

shakcho pushed a commit to shakcho/Docusaurus that referenced this pull request May 17, 2019

feat(v2): easier plugin theme components swizzling (facebook#1436)

fa3d64d

* feat(v2): easier plugin theme components override * add context * refactor again * rename eject -> swizzle * nits

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(v2): easier plugin theme components swizzling #1436

feat(v2): easier plugin theme components swizzling #1436

endiliey commented May 6, 2019 •

edited

Loading

docusaurus-bot commented May 6, 2019 •

edited

Loading

docusaurus-bot commented May 6, 2019 •

edited

Loading

endiliey May 6, 2019

yangshun May 7, 2019

yangshun May 7, 2019

yangshun May 7, 2019

yangshun left a comment

endiliey commented May 7, 2019

feat(v2): easier plugin theme components swizzling #1436

feat(v2): easier plugin theme components swizzling #1436

Conversation

endiliey commented May 6, 2019 • edited Loading

Motivation

Ejecting theme from plugin to override it easily

Refactoring

Example

Have you read the Contributing Guidelines on pull requests?

Test Plan

docusaurus-bot commented May 6, 2019 • edited Loading

docusaurus-bot commented May 6, 2019 • edited Loading

endiliey May 6, 2019

Choose a reason for hiding this comment

yangshun May 7, 2019

Choose a reason for hiding this comment

yangshun May 7, 2019

Choose a reason for hiding this comment

yangshun May 7, 2019

Choose a reason for hiding this comment

yangshun left a comment

Choose a reason for hiding this comment

endiliey commented May 7, 2019

endiliey commented May 6, 2019 •

edited

Loading

docusaurus-bot commented May 6, 2019 •

edited

Loading

docusaurus-bot commented May 6, 2019 •

edited

Loading