fix(v2): allow using classic theme/preset without the docs plugin

[slorber]

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

[docusaurus-bot]

Deploy preview for docusaurus-2 ready!

Built with commit 14f6bf5

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

[slorber]

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 docs: false in config, which probably make more sense in your case than loading uselessly the docs plugin, as you don't want to use it anyway.

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:

• classic preset loads the docs plugin, but allow to have no docs folder
• classic preset does not load the docs plugin, but we have to fallback in classic theme with the annoying useDocs file.

Do you think one solution is better than the other?
It seems before my refactor we had solution 1, and this PR enables solution 2.
Should we keep using solution 1?

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

[SamChou19815]

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 docs: false in config, which probably make more sense in your case than loading uselessly the docs plugin, as you don't want to use it anyway.

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:

• classic preset loads the docs plugin, but allow to have no docs folder
• classic preset does not load the docs plugin, but we have to fallback in classic theme with the annoying useDocs file.

Do you think one solution is better than the other?
It seems before my refactor we had solution 1, and this PR enables solution 2.
Should we keep using solution 1?

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.

[SamChou19815]

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.

[slorber]

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))

[slorber]

Seems to work according to the tests but there is an annoying webpack warning, not sure how to improve this.

[slorber]

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.

[slorber]

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