feat: structured data faqs - not fully working; basis for discussion

[johnnyreilly]

Pre-flight checklist

• I have read the Contributing Guidelines on pull requests.
• If this is a code change: I have written unit tests and/or added dogfooding pages to fully verify the new behavior.
• [] If this is a new API or substantial change: the PR has an accompanying issue (closes #0000) and the maintainers have approved on my working plan.

Motivation

I previously built a Structured Data FAQs plugin: https://johnnyreilly.com/docusaurus-structured-data-faqs-mdx

After I did that I discovered discussion of it as a feature here: https://docusaurus.io/feature-requests/p/creation-of-structured-faq

@Josh-Cena had suggested it would be good to have this built in. I started hacking together something to do that. This approach parses MD(X) files looking for ## FAQs and uses child headings and their answers to construct structured data FAQs as well.

This PR is that. There's a number of issues:

1. When running locally the plugin I've built is invoked multiple times - the FAQs are picked up in all initial runs but vanish in the final run - I'm mystified as to what is happening here. Any experts on remark plugins being invoked multiple times, but with different inputs on subsequent runs? Weird.
2. I'm not totally sure that, I've cracked how to pass through values from an remark plugin to the Docusaurus blog loader. I sort of copied the TOC approach. It doesn't seem to quite work.
3. Is this a good API design anyway? Would perhaps having FAQs as part of Frontmatter be better instead? Maybe Structured Data FAQs aren't that important anyways.

This PR is a (not quite) POC - and before I advance it further, I wanted to see if people saw value in it. Maybe not. If they do, I'd appreciate some pointers on solving the problems.

Also happy for this to be closed - maybe this isn't a good direction.

Test Plan

Test links

Deploy preview: https://deploy-preview-_____--docusaurus-2.netlify.app/

Related issues/PRs

[slorber]

I'm not sure to understand everything yet but that looks a bit complicated and opinionated API to me.

Is this need so common to justify the creation of a core remark plugin, enabled by default?
Couldn't this benefit other MDX-based sites as well (like Next.js/Astro?). I feel it does not really belong in Docusaurus core.

Couldn't we use a theme-common helper component for those that want to create a FAQ? Your solution here looks much simpler: https://johnnyreilly.com/docusaurus-structured-data-faqs-mdx#the-faqstructureddata-mdx-component

[slorber]

That looks quite opinionated to use hardcoded values like this and probably does not support i18n where headings will be translated

[slorber]

Does not look like MDX v2, we merged the PR so the TOC code you got inspired from is probably very different now 🤪

[johnnyreilly]

There more I think about it, the less I'm convinced this is a great idea / implementation. I think I'm going to close this as a consequence.

[johnnyreilly]

Couldn't we use a theme-common helper component for those that want to create a FAQ? Your solution here looks much simpler: https://johnnyreilly.com/docusaurus-structured-data-faqs-mdx#the-faqstructureddata-mdx-component

I think this is a good idea @slorber. I'd be happy to contribute the FAQs component to Docusaurus as a shared component if that would be helpful?

[slorber]

Yes why not

Was wondering if it wouldn't be simpler to add the structured data directly to the html elements instead of adding extra scripts?

Like we do for blog posts:

export default function BlogPostItemContainer({
  children,
  className,
}: Props): JSX.Element {
  const {frontMatter, assets} = useBlogPost();
  const {withBaseUrl} = useBaseUrlUtils();
  const image = assets.image ?? frontMatter.image;
  return (
    <article
      className={className}
      itemProp="blogPost"
      itemScope
      itemType="http://schema.org/BlogPosting">
      {image && (
        <meta itemProp="image" content={withBaseUrl(image, {absolute: true})} />
      )}
      {children}
    </article>
  );
}

---

On the usage API side, how would we use the FAQ components?

With Docusauurs v3 / MDX 2 there's a new CommonMark mode (#3018) and it would be nice if this feature can be used by both .md and .mdx files.

I think we have 2 choices then:

• automatically register a <faq> component in the MDX provider
• use a Remark directive:

:::faq[My FAQ Title]

My FAQ Content

:::