facebook / facebook/docusaurus

Content plugins should prevent usage of a parent folder as mdx source path

Aperta
#9,027 8 commenti 1 reazione 0 assegnatari Vedi su GitHub
domain: content plugin domain: dx proposal
Lingua principale
TypeScript
Stelle
66.2k
Fork
10k
Merge medio
1g 3h
PR unite (30g)
52

Descrizione

### 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.

Guida per i contributori

Apri la guida per i contributori

Valutazione

Questa issue non è ancora stata valutata.

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.