facebook / facebook/docusaurus

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

Ouverte
#9,027 8 commentaires 1 réaction 0 personnes assignées Voir sur GitHub
domain: content plugin domain: dx proposal
Langage dominant
TypeScript
Étoiles
66.2k
Forks
10k
Merge moyen
1 j 3 h
PR mergées (30 j)
52

Description

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

Guide de contribution

Ouvrir le guide de contribution

Évaluation

Cette issue n'a pas encore été évaluée.

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.