Docs / blog / pages: createFrontMatter callback to transform front matter

[christianvoigt]

💥 Proposal

We have a collection of Markdown articles that we want to use a) as a data source for a Docusaurus site and b) as a data source for Pandoc to generate pdfs from them via Latex (these will be printed out and used in schools and universities).

Pandoc expects multiple authors to be listed in the frontmatter "author" field, while Docusaurus expects them to be listed in the "authors" field. It would be great if the blog plugin would either also accept multiple authors in the "author" field or (even better) offer a method to provide a custom metadata provider that can override the default behaviour of the blog plugin and create the blog metadata from the Markdown frontmatter. Maybe this is already possible, but I could not find a way in the docs or by taking a quick look at the source code.

Keeping Markdown source files for blog articles decoupled from any specific publishing pipeline does make sense in general and such a customization option in Docusaurus would make it much easier to do so.

[slorber]

Agree, and I plan to add a hool like createFrontMatter allowing you to transform existing frontmatter from Pandoc schema to Docusaurus schema

This has been discussed in a few issues already (like https://github.com/facebook/docusaurus/issues/5478#issuecomment-912389209) and I plan to implement this soon

[slorber]

@Josh-Cena indeed this issue is important as it solves multiple use-cases in a generic way. It's not my main focus currently as it doesn't really block 2.0, so if you want to work on it 👍

Maybe we could use a parseFrontMatter hook instead:

• users can strip a copyright at the top (recently requested)
• users can use a faster parsing lib or whatever they want with more flexibility

My proposal:

const config = {
  // we'll later add more markdown-related global configs
  markdown: {
    parseFrontMatter: async ({
      plugin,
      content, // markdown file content string
      defaultParseFrontMatter // reuse existing utils parseFrontMatter
    }) => {
      const contentWithoutCopyright = removeCopyright(content);
      const { frontMatter, markdown } =
        plugin.name === "docs" && plugin.id === "ios"
          ? await customiOSParser(contentWithoutCopyright)
          : defaultParseFrontMatter(contentWithoutCopyright);
      return {
        frontMatter: customFrontMatterNormalization(frontMatter),
        markdown
      };
    }
  }
};

We should avoid adding a parseFrontMatter option to plugins options for now, as a global API may be good enough.

Does it make sense?

[Josh-Cena]

Yes, this makes sense👍 And will probably be the first step towards #4625

[slorber]

Another use-case to disable frontmatter draft: https://github.com/facebook/docusaurus/discussions/7995

[slorber]

Use-case: reading frontmatter of other locales (mostly the default locale). IE when building fr, access both en+fr frontMatter

https://github.com/facebook/docusaurus/discussions/8197

[slorber]

Use-case: process frontMatter.description to replace variables/placeholders with real value.

https://github.com/facebook/docusaurus/issues/395#issuecomment-1375539610