fix(v2): allow using classic theme/preset without the docs plugin #3382
Conversation
|
Deploy preview for docusaurus-2 ready! Built with commit 14f6bf5 |
|
Hey @SamChou19815 , this is an attempt to fix #3360 I also added a setup that looks like yours in our deploy previews so that we don't regress on this usecase: https://deploy-preview-3382--docusaurus-2.netlify.app/blog-only/ For classic preset without docs, I just allowed to pass I didn't find a good solution for the useDocs hook so for now I also added a dummy file. Currently, it seems the easy fix has 2 choices:
Do you think one solution is better than the other? At the same time, solution 2 would allow to use classic theme + blog plugin (like you tried) without using the classic preset, so it looks more flexible to me and allow better composition patterns |
I think solution 2 makes more sense. Solution 1 will still suffer from the issue of emitting missing docs folder warning. At least for me, I stayed on preset-classic with docs plugin enabled blog-only mode because it requires less config. The new solutions seem to only require one line of additional config and I think that's fine. |
| // See https://github.com/facebook/docusaurus/issues/3360 | ||
| // TODO find a better solution, this shouldn't be needed | ||
| export {}; | ||
| /* | ||
| throw new Error( | ||
| "The docs plugin is not used, so you can't require the useDocs hooks. ", | ||
| ); | ||
| */ |
There was a problem hiding this comment.
We seem to assume here that this dummy theme-classic file is the fallback, and the real hooks in plugin-docs can shadow it. I wonder whether this order of precedence is always desirable. I could imagine another potential use case that requires the opposite order of precedence: plugin-debug defines some default components, and let theme-classic or theme-bootstrap to provide better styling. Although I think the plugin-debug use case is probably less important.
There was a problem hiding this comment.
Thanks for your insights :) currently trying to figure this out by using the @theme-init alias and see if I can "forward" real useDocs impl conditionnnally, if docs plugin is available. Not sure how to do this properly, Webpack emits a warning on conditional requires (webpack/webpack#7713 (comment))
There was a problem hiding this comment.
Seems to work according to the tests but there is an annoying webpack warning, not sure how to improve this.
|
Thanks for your insight @SamChou19815 I suggest we merge this PR, even if it produces an annoying webpack warning it seems to work fine for solution2. The problem is that we currently don't have a good way for a plugin to expose client side utils like useDocs. This code should be provided by the plugin because it is useful for usage in multiple themes (like classic/bootstrap), but I don't think using @theme in plugin is the best solution for that (we loose typesafety by not emitting typedefs btw), so I'm not sure it's worth investing too much in a solution that would be changed later anyway. |
|
Basically this shows this webpack error on build:
webpack/webpack#7713 (comment) I was actually able to remove that warning using warningsFilter webpack option (not sure why but we seem to reimplement it in Docusaurus btw): https://webpack.js.org/configuration/stats/#statswarningsfilter |
Motivation
Attempt to fix the unability to use the classic theme/preset without the docs plugin
See #3360
Have you read the Contributing Guidelines on pull requests?
Yes
Test Plan
/blog-only/deploy preview