Is there a way to generate description for imported MDX files?

[allenscha]

We're testing the "Importing Markdown" feature for our multi-platform SDK documentation. In our case, a single MDX containing the whole content of the page (along with some custom conditional processing) is imported by each platform's parent documents. Some of the pages will use this import scheme, while the rest of pages will be in plain Markdown.

However, it seems that description is not generated for the pages using this import scheme. This means that, if we use autogenerated sidebar and category page with DocCards, no summary would appear for the pages using the import scheme. Also, SEO for the page will be degraded.

Is there a way to export the description of the imported MDX so that it can be used as the description of the parent pages? (similar to pseudocode shown below)

import Content, {
  frontMatter as FrontMatter,
} from './_markdown-partial-example.mdx';

<Content />

{frontMatter.description} = FrontMatter.description;

A workaround might be be using description field in the front matter of all parent pages (or leaving only the first paragraph of the content before using the partial component in the parent pages), but we'd like to see if there's any better way to solve this.

[slorber]

However, it seems that description is not generated for the pages using this import scheme

I don't think we generate any description here: either you provide it explicitly, or you don't. The description generation does not happen at the front matter level, and the front matter object remains untouched with description: undefined unless provided explicitly.

Afaik we don't allow any front-matter on partials because we don't use any.

---

Is there a way to export the description of the imported MDX so that it can be used as the description of the parent pages? (similar to pseudocode shown below)

No I don't think we have support for that.

---

My goal in Docusaurus v3 is to introduce a Markdown directive syntax like this:

::import{path='./_markdown-partial-example.mdx'}

Unlike JSX imports, the imported content would be "inlined" inside the parent page, and the description generation (not based on front matter) would be able to see the imported content.

This would also fix the TOC problem, see #3915

[allenscha]

Thank you for detailed explanation.

Regarding the TOC issue, the only workaround in Docusaurus v2.x seems to be exporting the TOC of a partial and injecting it into the swizzled TOC-related components (replacing the TOC of the page importing the partial), but this works only for a scenario using partials for whole-page content, so it's limited. Good to hear that the limitation can be resolved in v3.

[slorber]

The TOC issue is not just a Docusaurus issue but an issue for any tool that uses MDX somehow. Even the "official" remark-toc plugin (https://github.com/remarkjs/remark-toc) does not have the ability to handle MDX imports. We'll try to solve this problem but it does not come out of the box. In any case if you are motivated enough you can build your own remark plugin to solve it in userland, because in the end our solution will be a remark plugin. I admit it's probably not easy to build though, even for us.

[allenscha]

Hi @slorber,

Regarding this importing feature, one of my colleagues pointed me to a plugin:
https://github.com/simologos/docusaurus-plugin-includes

One example of project actively using the plugin:
https://github.com/whatap/docusaurus-docs

We verified that the plugin does not handle the multi-instance setup, but it seems to work OK with a single instance having versioning and i18n. I hope that their implementation might be helpful to you.

[slorber]

@allenscha I didn't have time to audit this plugin deeply but it looks like it's hijacking our MDX loader to process mdx files with regexes to find {@include statements. That probably works but feels a bit hacky to me.

With Docusaurus v2 you could probably do the same with an escape hatch I added in (#8288), cc @simologos:

const config = {
  markdown: {
    // Gives you opportunity to apply your own string processing before the MDX compilation
    // Usage is NOT recommended, use this as a last resort escape hatch or temporarily)
    preprocessor: ({ filePath, fileContent }) => {
      return fileContent;
    }
  }
};

Anyway: I think using a Remark-directive syntax in Docusaurus v3 will be a better option and I'd like to provide it out of the box later.