Allow a single docs folder to be consumed by 2 docs plugin instances (use-case: normal vs embed/iframe docs)

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

• I’m using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io.
• I have read the console error message carefully (if applicable).

Description

If I add the docs plugin to the list of plugins (multi-instance) and I point it to the same folder that the preset is already pointing to (docs by default), the build process stops working and I see the following errors:

SyntaxError: /code/src/......../index.mdx: Identifier 'React' has already been declared. (46:184)

I believe the bug might be caused by the way each mdx file is being processed. Because a mdx file is (basically) a JSX file, import React from 'react'; is being prepended at the top of each file. But since I have two instances of the docs plugin pointing to the same folder, the import statement is being prepended twice (hence the error).

I made a minimal repro codesandbox.

Reproducible demo

https://codesandbox.io/s/trusting-rosalind-sc4s15

Steps to reproduce

1. Open the link
2. Open a new tty and type npm run build
3. The build will fail.
4. Comment the plugins section of the docusaurus.config.js
5. Run npm run build again.
6. The build will succeed.

Expected behavior

I should be able to point multiple instances of the docs plugin to the same folder.

Actual behavior

The build crashes.

Your environment

• Public source code: N/A
• Public site URL: N/A
• Docusaurus version used: 2.0.0-beta20
• Environment name and version (e.g. Chrome 89, Node.js 16.4): N/A
• Operating system and version (e.g. Ubuntu 20.04.2 LTS): N/A

Self-service

• I’d be willing to fix this bug myself.

[alexandernst]

• why do you want to embed docs?

I have a product with a lot of “elements” (think about it as if the product was a 3D viewer of a car and each element a piece of that car). I want to point users to the documentation site and let them read the entire doc, but I’d also like to be able to show the particular documentation page for each piece.

• how do you want to embed the docs? (popup, iframe, WebView…)

When each element is clicked a modal window (containing several config options) is shown. Embedding the docs inside an iframe in a tab in that modal window sounds like a reasonably good idea to me.

• do you need to embed the whole docs folder, or just a few docs?

Each “piece” will have it’s own document page, so I’d show only that particular doc page.

• can you provide a production URL of a real doc that you would like to embed?

No, none of this is publicly available 😦

• do you care much about the embedded doc URL? (ie should it start with /docs/ vs /embed)

Not at all. That would be an iframe, so the url doesn’t really matter.

• what should happen if the user clicks a link on that page?

Hmmm 🤔 haven’t really thought about that. Maybe go to whatever link the user clicked, but the “embedded” version?

• it creates a different canonical URL for a doc that has exactly the same content, which may be bad for SEO (although google may understand this, I’m not sure it does. Note that for docs version, we may be able to add additional metadata in pages in the future to mitigate this)

Indeed. Maybe all of this could be avoided by implementing #5046

• have you tried injecting custom CSS in the iframe/webview? You may try to manually include it in a hacky way as a post-build step for example, and only add the class if the iframe is loaded with a given querystring ?embed=true)

That really sounds like a hacky solution, not my style I’m afraid.

• have you tried creating a custom page for the doc you want to embed, and importing the MDX file you want there? You wouldn’t need to apply a layout on this page.

That is theoretically possible, but I’ll have hundreds of “pieces”, which means hundreds of “doc pages”. I’m afraid that will grow up to “unmanageable” really fast.

• Another weird workaround would be to try using 2 distinct Docusaurus sites 😅

I’d rather just copy (on build time) the entire “docs” folder and do it with 2 instances of the docs plugin.

[Josh-Cena]

I don’t really know. I don’t think it’s possible with today’s setup, which is why I’m still leaving it open 😃 But it’s definitely legitimate and we’ll figure out a way to do it. Sorry if you think it’s going to be a quick little bug fix—it’s probably more complicated than we have thought.

@slorber will be back tomorrow, and maybe he can have some opinions to offer as well.