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 our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Cannot load docs from outside local package root when running as a Yarn workspace #9938
Comments
Docusaurus docs are transpiled by MDX to React components. The key thing to understand is that your docs are like React code, and the appropriate dependencies must be available to them. This usually works fine with most monorepo tools, because they would hoist the dependencies at the top of your monorepo Yarn 2+ uses a Plug and Play mode by default, which behaves a bit differently than traditional monorepo tools, and is "stricter" You can use any of those solutions to fix the problem under Yarn 2+: Disable PnP mode: yarn config set nodeLinker node-modules
yarn install
yarn workspace docs start Hoist the dependencies at monorepo root yourself yarn add @mdx-js/react@npm:3.0.1 react@npm:18.2.0
yarn workspace docs start Unfortunately it's hard for us to make Docusaurus work out of the box with all monorepo tools and fancy setups users might attempt to use, but the general idea remains that the appropriate dependencies should be available to docs, no matter how those dependencies get wired. |
@slorber thank you for your quick and detailed reply. Hoisting the imports to the root has some difficulties but we've managed to get a "good enough" version working. We've lost things like prism code syntax highlighting and admonitions. I assume this is likely the same issue and I need to hoist a variety of other packages. I tried with these but it still didn't seem to work. Does anything come to mind? yarn add @docusaurus/preset-classic @docusaurus/plugin-content-docs @docusaurus/core prism-react-renderer |
To be honest I don't really have any expertise in Yarn PnP system and don't use it myself 😅 I remember it was challenging to get our e2e tests pass under PnP but it's mostly @Josh-Cena that fixed those as far as I remember. Afaik there are several options you can try, such as: |
Thanks @slorber. Neither of those options helped, but I'll look into this deeper when I have time. We're in a "good enough" state for now. I appreciate your help so far ❤️ . |
Great 👍 Maybe @arcanis could help you, he's using Docusaurus on the Yarn website and probably knows how to handle this situation better than I do 😄 |
Nice, keen to hear more on how people have solved / worked around this! I guess it might make sense to add a little more info on the reasoning for including docs outside the actual docusaurus website. I run two docs websites which document a monorepo using Yarn workspaces. In both cases I actually want to include documentation directly from the package README's. e.g. a monorepo structured like this;
in my docusaurus navigation I have a main menu item of "packages" which then contains the documentation for each individual package. I find this pattern works really well as it allows us to keep the README's as the central documentation for each package. |
I'm using npm workspaces with nx and i'm facing a similar problem. I can't import a react component library to use on the live editor, but if I take my site outside the monorepo it works. |
@oliveirarafa this issue is about Yarn PnP and not related to the live editor. What you encounter is probably unrelated and we'd need a minimal https://docusaurus.new/stackblitz repro to investigate as a separate issue. |
Have you read the Contributing Guidelines on issues?
Prerequisites
npm run clear
oryarn clear
command.rm -rf node_modules yarn.lock package-lock.json
and re-installing packages.Description
When adding Docusaurus as a workspace in a Yarn 2+ project, the docs plugin will not loads docs from outside the Docusaurus project root. Instead, an import error message is displayed for each markdown file.
A reproduction is available here: https://github.com/snikch/docusaurus-yarn-workspace-repro
An example without Yarn workspaces which shows loading a directory above works fine is available on the
working
branch.Reproducible demo
https://github.com/snikch/docusaurus-yarn-workspace-repro
Steps to reproduce
Expected behavior
Docusaurus starts and renders docs pages.
Actual behavior
Docusaurus cannot render markdown docs due to import issues.
Your environment
Self-service
The text was updated successfully, but these errors were encountered: