Docusaurus: Include .md file in another

[jacarma]

Is this a bug report?

No, feature request

Have you read the Contributing Guidelines on issues?

Yes

Environment

Macos

Steps to Reproduce

1.
2.
3.

Expected Behavior

I would like to "include" a piece of markdown inside other markdown pages.

We are using Docusaurus to write the docs of a component library. Components have a set of configurable attributes and some of them are shared. For example every component have a label and a description, the input components have disabled and required attributes, the components which display a list of items have the url to query the items, the pagination, etc.

It would be very useful to have these common subsets of attributes in different .md files so I could "include" the ones that apply into every component page.

If not, we have to 1. copy and paste these attributes in every component (not good for maintainability) or 2. use links instead of including (not good for UX)

Actual Behavior

I couldn't find this feature in Docusaurus

Reproducible Demo

[zenflow]

@jacarma This doesn't necessarily need to be supported by Docusaurus directly.. you can find or create a remarkable plugin to do this and use it in siteConfig.markdownPlugins. In this way you can implement whatever non-standard markdown features you can conceive.

(FWIW I would opt for simply presenting a document containing that info and using links... I don't think it's too inconvenient for users to navigate and open multiple tabs if necessary, and it clearly informs them what the common attributes are)

[yangshun]

@jacarma I haven't seen any existing usage of importing Markdown in other Markdown pages before. As @zenflow said, it would be more appropriate to use/write a Markdown plugin to do what you need.

We could feature a list of common Markdown plugins to show how you can have some features which Docusaurus doesn't support natively but can be achieved through plugins. 😀

[xpluscal]

@jacarma @yangshun do you have a specific plugin at hand that would enable this functionality?

[jacarma]

I had to use links

[dotansimha]

If someone needs it, with v1, you can add this plugin: https://github.com/dotansimha/graphql-code-generator/blob/b1820380fff5692b4c3a5be1335dd94ac572dc1f/website/remarkable-plugins/import-md.js

And load it as specified here: https://github.com/dotansimha/graphql-code-generator/blob/master/website/siteConfig.js

Then, you can do in your .md files:

{@import: ../other-file.md}

[kripod]

Is it possible to do this with v2? I would like to embed the CONTRIBUTING.md and CODE_OF_CONDUCT.md files from the repo's root, without the beginning # Title (<h1>Title</h1>).

[dotansimha]

@kripod I created the same for v2, it's a bit buggy but works.

The plugin is here: https://github.com/dotansimha/remark-import-partial , and usage example: https://github.com/Urigo/graphql-mesh/blob/master/website/docusaurus.config.js#L82-L87

[kripod]

@dotansimha Thank you for the response!

It turns out that Docusaurus v2 supports MDX transclusion by default. However, only files from website/docs/ can be imported, due to the limitation of the current webpack loader configuration.

I created a PR (#2619) to resolve this issue. Importing .md(x) files which are located at an immediate parent directory of website/docs/ should be possible soon.