include external sourced files into build

[vanbasten17]

🚀 Feature

Be able to pull plain text information from external sources and build it up with docusaurus build.

Example: Retrieving an external markdown file to be injected into a specific route.

Have you read the Contributing Guidelines on issues?

Yes

Motivation

We would like to source github's READMEs and build them with docusaurus build for our project documentation (botonic).
I have seen a related issue here: #2725 , but couldn't find the mentioned plugin in docusaurus docs.

Pitch

I think it's pretty common for open-source projects to have several plugins in order to add extra functionalities to them. In our situation, every plugin is documented itself in its corresponding README in github which serves as the main documentation as for example Gatsby does with their plugins, so this is the main reason of being implemented. This is our current plugins library.
To do so, maybe it would be useful to have a list of urls (pointing to an url with the corresponding .md in this case) and mapping them into desired routes in the project.

Many thanks! 😊 You have an awesome ongoing project!

[slorber]

Hi, this is something I'd like to support.

However, keep in mind that Github README is commonmark, and we are using MDX. The implementation diverge on the HTML elements, so you'll have to avoid using such elements if you want the readme file to work in both Docusaurus and Github pages.

Unfortunately, for now MDX is not 100% compatible with commonmark (mdx-js/mdx#1125), but it'd like to make it easier to use a commonmark compatible mode, in particular for these usecases (related to #3009 as well)

[slorber]

BTW, you can already create a docusaurus plugin that creates one page per plugins you have in the monorepo, using a commonmark compatible parser, but you'll have to implement this yourself with plugin lifecycles.

My comment above is mostly if you want to use package READMEs as a part of the docs plugin, have a sidebar, versioning features etc... so it really depends on your need.

[vanbasten17]

Hi @slorber , thanks for your time! Would you mind sharing with me some guidelines to create a plugin to support this? I'll try to do this if I can invest some time. Thanks

[slorber]

@vanbasten17 the best is to read the docs (https://v2.docusaurus.io/docs/lifecycle-apis/), understand the lifecycles to read FS data, create pages etc...
To get some inspiration, the pages plugin is likely easier to understand.

But you'll have to figure out how to replace MDX by a regular MD parser/renderer. It's not something I ever did so I can't really help you more than that.

[Josh-Cena]

You can now import external MD files: https://github.com/facebook/docusaurus/blob/main/website/community/5-changelog.md

[benlongo]

Unfortunately that link appears to be dead now. I was able to find it here https://github.com/facebook/docusaurus/blob/v2.0.0-beta.15/website/community/5-changelog.md