facebook / facebook/docusaurus
Content plugins should prevent usage of a parent folder as mdx source path
- Vorherrschende Sprache
- TypeScript
- Sterne
- 66.2k
- Forks
- 10k
- Ø Merge
- 1 T. 3 Std.
- Gemergte PRs (30 T.)
- 52
Beschreibung
### Have you read the Contributing Guidelines on issues?
- [X] I have read the [Contributing Guidelines on issues](https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#issues).
### Motivation
Some users attempt to do:
```js
presets: [
[
"classic",
({
docs: {
path: "..",
// ...
}),
],
],
```
See https://github.com/facebook/docusaurus/discussions/9002
This is bad because using the site root (or any of its parent) as the source of md/mdx content will register a mdx loader for that folder, and lead to conflicts with the blog/page plugins that are nested inside that folder.
The error message is not very clear, such as:
```
[ERROR] MDX loader can't read MDX metadata file "/home/md/github/design-docs/docs-website/.docusaurus/docusaurus-plugin-content-docs/default/site-src-pages-markdown-page-md-393.json". Maybe the isMDXPartial option function was not provided?
```
I think we should improve the DX and fail-fast, forbidding the use of the site folder (or any of its parent) as content (md/mdx) source root.
Eventually the error message could mention that if user wants to have some content folders upper in the tree (like it was in Docusaurus v1: `../docs`), it's possible to use that specific folder inside a parent dir. It can be useful to also mention multi-instance as an option (see https://github.com/facebook/docusaurus/discussions/9002#discussioncomment-6048315)
Technically it might be possible to order mdx-loaders in an order that could make it work, but I doubt it's a good idea to allow that anyway and could lead to more annoying problems too, for example users trying to use autogenerated docs but it picks content from blog/pages too... So I think it's safer to just forbid this entirely.
To generalize: the problem is to have one content folder nested inside another. Unfortunately due to the modular nature of Docusaurus (the concept of a "content folder" is plugin-specific), it's probably not possible to generalize the solution and we can only prevent he most common case: declaring a direct site parent folder as content folder.
### Self-service
- [X] I'd be willing to do some initial work on this proposal myself.
Beitragsleitfaden
Bewertung
Dieses Issue wurde noch nicht bewertet.