Docusaurus on an existing repo with docs one level up

[mderazon]

Hello. I am creating a docusaurus project inside an existing repo. My docs are one level up from the docusaurus project

.
├── docs-website
│   ├── README.md
│   ├── babel.config.js
│   ├── blog
│   ├── docs
│   ├── docusaurus.config.js
│   ├── sidebars.js
│   ├── src
│   │   ├── components
│   │   ├── css
│   │   └── pages
│   └── static
│       └── img
├── fol-23
│   ├── feat-1
│   │   └── doc1.md
│   ├── feat-2
│   │   ├── doc1.md
│   │   ├── doc2.md
│   │   ├── doc3.md
│   │   └── doc4.md
├── fol-24
│   ├── feat-1
│   │   └── doc1.md
│   ├── feat-2
│   │   ├── doc1.md
│   │   └── doc2.md
│   ├── feat-3
│   │   ├── doc-1.md
│   │   ├── doc-2.md
│   │   ├── doc-3.md

Any way to tell docusaurus to refer to md files in the folders up from the docusaurus project ?
I thought about adding

path: "..",
include: ["fol-*/**/*.{md,mdx}"],

To docusaurus.config.js :

  presets: [
    [
      "classic",
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        docs: {
          sidebarPath: require.resolve("./sidebars.js"),
+          path: "..",
+         include: ["fol-*/**/*.{md,mdx}"],
          // Please change this to your repo.
          // Remove this to remove the "edit this page" links.
          editUrl:
            "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/",
        },
        // ...
      }),
    ],
  ],

But it is throwing some errors.

Any idea how to achieve this ?

Thanks

[slorber]

This is the way, but you probably don't need to modify the include, and you need one docs plugin instance for each parent folder.

path: '../fol-23`

But it is throwing some errors.

We don't know what those errors are so we can't help fixing them 🤷‍♂️

Create a small repro if you want more help

[mderazon]

Thank you for your answer.
Here's the repo:
https://github.com/mderazon/design-docs

$ cd docs-website
$ npm start
> docs-website@0.0.0 start
> docusaurus start

[INFO] Starting the development server...
[SUCCESS] Docusaurus website is running at: http://localhost:3000/

● Client █████████████████████████ building (46%) 2/3 entries 593/640 dependencies 154/239 modules 83 active
 babel-loader › node_modules/@docusaurus/plugin-debug/lib/theme/DebugConfig/index.js

[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?
[ERROR] Error: ENOENT: no such file or directory, open '/home/md/github/design-docs/docs-website/.docusaurus/docusaurus-plugin-content-docs/default/site-src-pages-markdown-page-md-393.json'
[INFO] Docusaurus version: 2.4.1
Node version: v18.13.0

[slorber]

This repro also fails if I disable your docs plugin, so it is probably not the problem in the first place.

Start by creating a new runnable Docusaurus site, and only then add your docs changes. In your case I can't easily debug it because it might be related to anything.

I suspect it's your repo setup: it's not a good idea to nest one package inside another without using hoisting (npm/yarn workspaces).

If you want more help, please provide:

• commit 1: a newly initialized site that can be run
• commit 2: shows a clear diff and the site is now failing due to the changes

[mderazon]

Hi Sébastien.
Here's the clean working commit:
https://github.com/mderazon/design-docs/tree/b2c70fc9a1ad1641415af53b0a21c971c2386a21

And here's the diff with the commit that breaks it (one commit after the working state):
mderazon/design-docs@b2c70fc...60feecb

Thanks again

[slorber]

Using path: '..' is actually not a good idea, because this folder includes your whole site, including your blog, pages etc... this creates conflicts that we can't really manage. IMHO we should forbid you to use a direct parent folder.

If you want to have 2 folders, you need to configure 2 docs plugin instances:

"presets": [
    [
      "classic",
      {
        "docs": false,
        "blog": false,
      }
    ]
  ],
  "plugins": [
    [
      "@docusaurus/plugin-content-docs",
      {
        "id": "pi-1",
        "routeBasePath": "pi-1",
        "path": "../pi-1"
      }
    ],
    [
      "@docusaurus/plugin-content-docs",
      {
        "id": "pi-2",
        "routeBasePath": "pi-1",
        "path": "../pi-2"
      }
    ]
  ],

Docs: https://docusaurus.io/docs/docs-multi-instance

---

In the future we'll try to forbid using path: '..' with a clear error message suggesting you to use multi-instance instead. Tracked here: #9027

[mderazon]

Thanks. In terms of DX, yeah it can be improved as the error message was very unclear

But I assumed that the combination of path and include keys:
https://github.com/mderazon/design-docs/blob/60feecb3d9a8ed43cfe5a9a28098ca6e232f4acc/docs-website/docusaurus.config.js#L42-L43
Will narrow down the docs to be searched only from the filtered path.

In my specific use case, there's an unknown amount of folders. I guess my only option is to nest them all under one folder ?

[slorber]

In my specific use case, there's an unknown amount of folders. I guess my only option is to nest them all under one folder ?

Yes, that's the solution I would use.

[enzofrnt]

I think we should be able to use this kind of architecture, as I mention here #9027