New Markdown header import_content_from

[felipecrs]

🚀 New Markdown header import_content_from

A user can specify the path to another Markdown file, which will be used to serve as the content of the current file. Especially useful for folks who want to use the repository's README.md as one of the docs in Docusaurus.

Have you read the Contributing Guidelines on issues?

Yes

Motivation

I want to use my README.md as one of my docs in Docusaurus, see this.

Pitch

Let's say we have a file docs/index.md. This file will be my entry-point page in the docs. So I would use the following Markdown headers on it (Front Matter):

---
slug: "/"
title: "Megatar"
---

But let's say that I wanted to use the contents of my existing README.md on this page. So, with the new header, I would do that:

---
slug: "/"
title: "Megatar"
import_content_from: "../README.md"
---

This enables me to use my README.md as one of the docs while I still keep it as is (without the Docusaurs Markdown headers) for the GitHub to render it cleanly.

[slorber]

Hi,

This is more complex than you might think.

First we use MDX, and it's not 100% certain than your github Readme will work fine when parsed with MDX (particularly embedded html blocks).

Second, each plugin (docs, blog, pages) has its own MDX/Remark/Rehype config and set of features, and the loading of docs is somehow sandboxed per plugin. For example, the docs plugin has advanced features that permit to resolve relative md file paths to URL links in the same doc version if you use versioning.

We do support MDX document partials, in case you want to embed one doc into another.
(https://v2.docusaurus.io/examples/markdownpageexample/#import-mdx-and-md-files).
This is however a bit limited, as the TOC feature is lost (afaik there is an issue somewhere)

But if the original doc is in ./docs, the imported doc must also be in ./docs to benefit from the same markdown loader setup as the original document.

As a workaround I suggest to copy the README in ./docs as a build step. You could have an empty/placeholder ./docs/README.md

We can see how to eventually support better your usecase, but it's not so simple, particularly as we'd like to support it in a generic way so that it's consistent for all source plugins, and maybe future community plugins.

[felipecrs]

First we use MDX, and it's not 100% certain than your github Readme will work fine when parsed with MDX (particularly embedded html blocks).

Perhaps there is some library that can convert MD to MDX?

Second, each plugin (docs, blog, pages) has its own MDX/Remark/Rehype config and set of features, and the loading of docs is somehow sandboxed per plugin. For example, the docs plugin has advanced features that permit to resolve relative md file paths to URL links in the same doc version if you use versioning.

For the relative path issues, I believe this should be fixed during the convert of the MD to MDX. Any relative path which contains ./docs/doc-a.md for example would need to be translated into ./doc-a.md (original relative path minus the docs root folder).

We do support MDX document partials, in case you want to embed one doc into another.
(https://v2.docusaurus.io/examples/markdownpageexample/#import-mdx-and-md-files).
This is however a bit limited, as the TOC feature is lost (afaik there is an issue somewhere)

Thank you! I'll take a look. But as you said, this requires that I at least copy the README to the docs folder.

As a workaround I suggest to copy the README in ./docs as a build step. You could have an empty/placeholder ./docs/README.md

This is what I do currently:

#!/bin/bash

script_dir="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
cd "$script_dir"

readme_file='../../README.md'
index_file='../../docs/index.md'

cat << EOF > $index_file
---
slug: "/"
title: "Introduction"
hide_title: true
---
EOF

cat $readme_file >> $index_file

https://github.com/felipecrs/megatar/blob/master/website/scripts/import-readme.sh

then:

{ 
  "scripts": {
    "build": "scripts/import-readme.sh && docusaurus build",
  }
}

https://github.com/felipecrs/megatar/blob/master/website/package.json#L8

However this sounds like a hack, this proposal was to make this in a more elegant way. :-)

[slorber]

Perhaps there is some library that can convert MD to MDX?

Afaik not atm, but I've opened this issue a few months ago: mdx-js/mdx#1125

We'd also benefit from such a tool to migrate from docusaurus v1 to docusaurus v2.

---

Yes, copying the files is a temporary workaround for now.

Unfortunately, I should focus on shipping i18n, and solving critical bugs that don't have any workaround, so won't work on this right now.
If you want to make it happen, submitting a PR right now is the best solution, but this might be quite complex to do correctly.

[Josh-Cena]

This is doable with MDX imports now—we can import from outside the plugin folder. Docusaurus uses this feature ourselves: https://github.com/facebook/docusaurus/blob/main/website/community/5-changelog.md