How to create mdx templates and passing props without frontmatter

[ygongdev]

Preliminary Checks

• This issue is not a duplicate. Before opening a new issue, please search existing issues: https://github.com/gatsbyjs/gatsby/issues
• This issue is not a question, feature request, RFC, or anything other than a bug report. Please post those things in GitHub Discussions: https://github.com/gatsbyjs/gatsby/discussions

Summary

I'm migrating my blog from Jekyll to Gatsby and I heavily relied on the Liquid templating language to create complex templates.

In Gatsby, this seems to be the equivalent of creating mdx templates where I can build new mdx by just passing props to the pre-made mdx templates. However, it was very difficult to find the right resources on how to do it.

I managed to figure out one potential way to do so and I was wondering if there is a better way. If not, I think this can be a valuable addition to the documentation.
Here's a gist

Steps to Resolve this Issue

1. Create a template.mdx
2. Create a post.mdx
3. Create a corresponding react component for template.mdx, e.g, template.js
4. In post.mdx, import template.js and pass your custom props to it
5. In template.js, use graphql to get the template.mdx's body and pass the custom props to MDXRenderer.
6. In template.mdx, render the custom props by surrounding it with <>{}</>

Here's a gist

[LekoArts]

Hi!

I think the part where you're rendering MDX inside MDX again is making this too complicated. The way I understand it you want to have a Table of Contents component that you can pass in a prop and that you can place anywhere in your MDX files.

I'd do it like this:

1. Create a toc.js file that has items and customProp as props. items will be the actual ToC content
2. You have the folder with your MDX files and use createPages API in gatsby-node.js to create the pages. In your src/templates/template-for-mdx-files.js you define the components prop on your MDXProvider component: https://www.gatsbyjs.com/plugins/gatsby-plugin-mdx/#shortcodes
3. Now the ToC component is available to every MDX file
4. For your MdxRenderer component inside src/templates/template-for-mdx-files.js you can pass a items prop: https://www.gatsbyjs.com/plugins/gatsby-plugin-mdx/#mdxrenderer - use the tableOfContents field on the mdx node for that
5. Now in your MDX files you can access props.items and can also use ToC without importing it

[ygongdev]

The concept is similar to making a large set of higher order components but the caveat is I prefer writing markdown instead of html hence why there’s a mdx and a react component. Since the MDXRenderer seem to only understand the mdx when it is in the AST and the only way I could turn the mdx into an AST is by making a mdx template and query that template in graphQL

[ygongdev]

@LekoArts Apologies for pinging, but I've been trying to wrap my head around how to best do this and I'm wondering if there is a way for customProps to be actual markdown content?

For example, take a look at this markdown using Liquid templating.

---
layout: post
title: "[LeetCode] 1. Two Sum"
category: LeetCode
---

{% include
  leetcode_table_of_content.md
  solution_name="straightforward-solution"
%}

{% capture problem_description %}
Given an array of integers, return **indices** of the two numbers such that they add up to a specific target.  
You may assume that each input would have ***exactly*** one solution, and you may not use the _same_ element twice.
{% endcapture %}

{% capture problem_example %}
{% highlight python %}
Given nums = [2, 7, 11, 15], target = 9,

Because nums[0] + nums[1] = 2 + 7 = 9,
return [0, 1].
{% endhighlight %}
{% endcapture %}

{% capture problem_input %}
{% highlight python %}
class Solution:
    def twoSum(self, nums: 'List[int]', target: 'int') -> 'List[int]':
{% endhighlight %}
{% endcapture %}

{% include 
  leetcode_header.md 
  title="1. Two Sum" 
  problem_link="https://leetcode.com/problems/two-sum/"
  problem_description=problem_description
  problem_example=problem_example
  problem_input=problem_input
%}

Basically, I can store markdown content via capture and feed it into another markdown template. (leetcode-header.md). You can imagine I've got many more templates like this as well. Can this be easily done in Gatsby?

[ygongdev]

For example, using the shortcodes and MDXProvider example.

I would have

import Header from './header.mdx';
import Toc from './toc.mdx';

const shortcodes = { Header, Toc } // assuming Header and Toc are both .mdx b/c I want to leverage markdown.

export default ({ children }) => (
  <MDXProvider components={shortcodes}>{children}</MDXProvider>
)

then

<Toc title="some-title" />

// How to pass dynamic variables like problem_description, which is markdown, to Header? I tried and it didn't assume to respect the markdown formatting.
<Header
  title="1. Two Sum" 
  problem_link="https://leetcode.com/problems/two-sum/"
  problem_description=problem_description
  problem_example=problem_example
  problem_input=problem_input
/>

[LekoArts]

Unfortunately I'm not familiar with Jekyll but it looks to me like you try to force the "Jekyll way of doing things" onto React/Gatsby. I can only give high-level comments since I don't have all the details but you'll need to change your approach to how you'd normally do it in Gatsby.

• Generally speaking if something doesn't need to be markdown formatted you can put it into the frontmatter of a post and then reference that both in your React template and in the MDX file itself.
• You can import other MDX files inside MDX files itself e.g. here's a practical example: https://github.com/system-ui/theme-ui/blob/develop/packages/docs/src/pages/index.mdx
• You can also use Markdown inside React Components you use in MDX:

import Component from "somewhere"

<Component>

Your **markdown** stuff

</Component>

You can certainly try to make it as modular as possible but what most people do is have one or two properties in their frontmatter, like layout or type and then they use that to use a different template in createPages of gatsby-node.js or they use it as a toggle for logic inside a single template (which will become huge with more and more toggles).

Most users I know also don't manually write their ToC but use the autogenerated one that you get from MDX itself.

[ygongdev]

I appreciate the response!
Although I do think this is not explicitly a Jekyll problem. If it wasn't for markdown, I can easily see how to do this with just React components.

I think the main gist of it comes down in the mdx parsing. When we query via graphQL, the body is not markdown, but rather some sort of AST I believe. The MDXRenderer seems to only understand the AST, but not the actual markdown. So if I'm trying to pass markdowns around without a way to parse it into an AST to feed into the MDXRenderer, it won't render correctly. I'm more than happy to be wrong though.

I will keep digging at this though and if I do figure something out, I'll update here! Thanks again!