facebook / facebook/docusaurus

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

オープン
#9,027 コメント 8 件 リアクション 1 件 担当者 0 名 GitHub で見る
domain: content plugin domain: dx proposal
主要言語
TypeScript
スター
66.2k
フォーク
10k
平均マージ
1日 3時間
マージ済み PR(30日)
52

説明

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

コントリビューションガイド

コントリビューションガイドを開く

評価

この issue はまだ評価されていません。

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。