2 sources of markdown files, 2 docs plugins or advanced config?

[MoOx]

Hi, I am new to Docusaurus.
I started with a preset-classic and I have 2 sources of .md files to consume:

• one source from the website repo itself (very classic)
• one source from the project folder where the source code is (.md files are near source code for convenience for now) (project added as a dev deps, so .md available in node_modules/{project}/src/**.md.

Should I use the docs plugin twice, or should I use a advanced config for one doc plugin instance?

Thanks for the help.

[MoOx]

Nevermind, I changed my workflow to have a single source.

[slorber]

hi !

You can only have one source folder per docs plugin instance currently, but we have a few users that generate md docs in this folder as a pre-build step.

For example this plugin add a cli that will generate md docs in ./docs from a GraphQL schema: https://github.com/edno/docusaurus2-graphql-doc-generator

So you can basically do the same and copy node_modules/{project}/src/**.md to ./docs

Using one or 2 instances depends on your use-case but multi-instance is mostly done for docs that are unrelated and do not need to link to each others, potentially having different versioning schemes (like ios/android for mobile SDKs)

[Siemienik]

Docusaurus has a possibility to set plugin id. IMO, It is the best way to handle external source (like API References):

https://docusaurus.io/docs/using-plugins#multi-instance-plugins-and-plugin-ids

module.exports = {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        path: 'docs',
        routeBasePath: 'docs',
      },
    ],
      [
      '@docusaurus/plugin-content-docs',
      {
        id: 'api',
        path: 'api',
        routeBasePath: 'api',
      },
    ],
  ],
};

[slorber]

It depends because it also prevents from versioning docs+api together, and also prevent from linking from one instance to another by using relative md paths (you need to use absolute paths instead, but we'll probably support relative links later)

[tomasdelvechio]

Hi I tried that, but I get this error message when I built:

Module parse failed: Assigning to rvalue (1:2)
You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file. See https://webpack.js.org/concepts#loaders
> ---
| id: intro_2
| title: Introducción a usuarios
 @ ./.docusaurus/registry.js 1:11612-11660 1:11476-11583
 @ ./node_modules/@docusaurus/core/lib/client/exports/ComponentCreator.js
 @ ./.docusaurus/routes.js
 @ ./node_modules/@docusaurus/core/lib/client/clientEntry.js
 @ multi ./node_modules/react-dev-utils/webpackHotDevClient.js ./node_modules/@docusaurus/core/lib/client/clientEntry.js

I add plugin section in docusaurus.config.js:

...
plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'users',
        path: 'users_docs',
        routeBasePath: 'users',
        sidebarPath: require.resolve('./sidebars-users.js')
      },
    ],
  ],
...

The sidebars-users.js file is:

module.exports = {
  menu: {
    General: ['intro'],
  }
};

In the users_doc/ directory I have 1 file with name intro.md and his content is:

---
id: intro
title: Introduction 
---

## Title

some trivial markdown content

What is wrong in this config?

[slorber]

Looks related to #3272

If you are using symlinks, it's your lucky day because II just merged the fix and it should become available in canary: https://docusaurus.io/community/canary