mdx-js
Parametrised markdown code blocks? #2288
-
|
I'm trying to understand how I can use variables in various markdown constructs, and I noticed that they work in some cases, like headers, lists, and explicit html code blocks: export const world = 'World'
Hello {world}!
# Hello {world}!
- Hello {world}!
One <code>Hello {world}!</code> TwoHowever I could not make them work in markdown code blocks: export const world = 'World'
Three `Hello {world}!` Four
```bash
Five
Hello {world}!
Six
```Am I missing something, or this is not yet implemented? |
Beta Was this translation helpful? Give feedback.
Replies: 7 comments 34 replies
-
|
It is indeed not implemented. |
Beta Was this translation helpful? Give feedback.
-
|
I see... Not very encouraging :-( The question is not theoretical, I am considering to migrate several sites from Jekyll (Liquid templates) to Docusaurus (MDX), and most of the pages (hundreds of them) have code blocks like this: I know I can rewrite this to html using Any other suggestions how to approach this migration? The Liquid template engine performs only textual substitutions, and this works pretty well. Unfortunately, with MDX, such textual substitutions seem not possible. :-( |
Beta Was this translation helpful? Give feedback.
-
|
You want to switch from one language to another. |
Beta Was this translation helpful? Give feedback.
-
|
Code may often contain syntax that would conflict with such interpolation. For example, consider the following MDX: This is a destructuring example in JavaScript:
```js
const { name } = person
```I think it would come as a total surprise if |
Beta Was this translation helpful? Give feedback.
-
|
To help you get started, it probably looks something like this: import { Code, Root } from 'mdast';
import { Plugin, Transformer } from 'unified';
import { visit } from 'unist-util-visit';
import { yourSubstitutionImplementation } from './some-module.js'
const remarkLiquid: Plugin<[], Root> = () => (ast) => {
visit(ast, 'code', (node: Code) => {
node.value = yourSubstitutionImplementation(node.value)
})
}
export default remarkLiquid; |
Beta Was this translation helpful? Give feedback.
-
|
I think this is a good starting point, thank you. Is Invoking the Liquid template engine is trivial, but I also have to parse the frontmatter, to get the substitution variables and pass them to the Liquid engine. |
Beta Was this translation helpful? Give feedback.
-
|
No, the above code looks for If you have frontmatter, you need to set up remark to understand that frontmatter. With https://github.com/remarkjs/remark-frontmatter. You also need to parse that frontmatter and expose it to plugins.
MDX expressions are not liquid variables. You now have two solutions to a problem (variables?) that do similar but different things. I think you will run into problems when you try and mix the two in your files. |
Beta Was this translation helpful? Give feedback.
-
Ah, this might not be exactly what I expected. The Liquid substitution is expected to be performed on the entire original file, and the result later parsed for nodes. Can this be done?
I definitely don't have your oversight, it might be so, but, if the substitution is done on the entire file, perhaps not necessarily, since these are two separate steps. With my limited understanding, I think that a pre-processing step with the Liquid engine, followed by the existing MDX logic, would be a very powerful combination, and would greatly simplify the migration from Jekyll. Without this, most (if not all) of my pages require lots of small edits, generally rewrites in the more complicated JSX syntax of the initial simple MD. BTW, Liquid allows much more than simple substitutions, it has lots of tags that can implement quite elaborate logic. For example here is another excerpt from another page which I have no idea how to convert from Liquid/Jekyll to MDX/Docusaurus: These two lines generate a bulleted list of links to some blog pages, filtered by a category field. If I can find a way to pre-process it, the result is plain markdown, it shouldn't be a problem. |
Beta Was this translation helpful? Give feedback.
-
Understandable! The original question was specifically about code, hence why the solution proposed was also about code.
Yes, you can use liquid before passing things to MDX.
The same is true for MDX.
This brings back my earlier comparison of using two programming languages together.
How to do this depends on your framework, particularly, React, and the language, as in JavaScript. <ol>
{
site.posts
.filter((post) => post.categories.includes('releases') && post.categories.includes('docus-mock'))
.map((post) => {
<li key={post.url}>
<a href={site.baseurl + post.url}>{post.title}</a>{' '}
<a href={post.download_url}>(download)</a>
</li>
}
})
}
</ol>
MDX is not plain markdown. |
Beta Was this translation helpful? Give feedback.
-
Right, the original question was about code because most of my pages include lots of code and manually rewriting them from markdown to JSX would make the biggest part of the migration effort. Also, since Docusaurus did not yet complete the migration to MDX 2, with MDX 1 I also have problems with lists, links, etc, practically the migration requires to fully rewrite every page, there is little to be reused. :-( I'll probably postpone everything until Docusaurus 3 is out, with MDX 2 and full ESM support, and then I'll re-evaluate everything. If I can automate the migration with some reasonably complex sed scripts, I'll try to convert the pages to MDX. If not, I have to decide if a Liquid pre-processing step is realistic or not.
For a new site I'd definitely go for MDX, but unfortunately I have hundreds of pages with liquid substitutions, and I'm trying to find a solution to make the migration less painful. To be exact, I have 20 smaller sites (each with 20-30 pages) and 2 large sites, each with 100+ pages.
I don't understand this. Why MDX cannot parse the page after Liquid does the textual substitutions? By the way, you have a (somehow) similar syntax problem, in JSX you use I am convinced that React/MDX/Docusaurus/etc represent a much more powerful solution, and I'd really like to do everything in the node/npm ecosystem, but unfortunately I do not have unlimited resources for this. FYI, in my desire to stay in the same ecosystem with my embedded system projects too, I created Anyway, regardless of my desire to get rid of Ruby and Jekyll, the Liquid template engine remains a very nice thing, and the JS implementation is really great. |
Beta Was this translation helpful? Give feedback.
-
It can. I made a mistake: for some reason I thought liquid would look for one brace too ( |
Beta Was this translation helpful? Give feedback.
-
|
Ok, no problem. Let's hope for the best, that the Liquid pre-processing will not be needed. |
Beta Was this translation helpful? Give feedback.
-
|
I mentioned earlier that I also have difficulties to migrate lists and/or links to MDX. Any idea why the following: is rendered (by the playground) as: and not as an image with a link, like GitHub does for the same content (the urls are fictive): ---> I tried to enable the Is this the expected behaviour? |
Beta Was this translation helpful? Give feedback.
-
|
This is expected behavior. The text you show is not “valid” markdown: it is not an image in markdown. Presumably, you are trying to use interpolation (liquid or JavaScript) there? |
Beta Was this translation helpful? Give feedback.
-
Aha! This was really useful, thank you! GitHub is less strict with these spaces. Is there a way (configuration option, plugin, etc) to switch to GitHub behaviour? |
Beta Was this translation helpful? Give feedback.
-
|
How do you mean GH is less strict? GH follows CommonMark:  |
Beta Was this translation helpful? Give feedback.
-
|
Indeed. My bad, sorry. I'll remove all spaces. |
Beta Was this translation helpful? Give feedback.
-
|
I think that now things are bit more clear. After Docusaurus will add support for MDX 2, hopefully most of my content will be accepted. The only remaining major issue is with code blocks, which require the In Docusaurus I saw that it is possible to pass a lot of options to code blocks, like line numbers to highlight, etc. I was wondering if it would be possible to add a new option to enable interpolation inside code blocs, something like: I think that this would solve the problem with a simple solution while preserving the markdown syntax, avoiding thus the rewrite to html, which is more tedious and also less readable. |
Beta Was this translation helpful? Give feedback.
-
You mean a plugin that identifies that the node is a code block, checks if the
An
Yeah, just that there are hundreds of them... And I have to change not only the back ticks into |
Beta Was this translation helpful? Give feedback.
-
Yep
It might not make a difference. The reason I ask is that I don’t know exactly what you want.
That should not be needed? Why do you think that is needed? |
Beta Was this translation helpful? Give feedback.
-
Hmmm, if after more than 20 messages I was not able to describe the problem, my communication skills should be really bad... I provided an excerpt from my existing markdown code in this comment, and you suggested a solution in the next comment. From that I got the idea to use a JS string template inside JSX html code. What I need is a solution to migrate my content to Docusaurus, with a not so complicated rewriting. BTW, your code has two small issues: because the apostrof is on the first line, the string starts with an empty line; also the string
Because the JS syntax for inserting expressions in a string template is |
Beta Was this translation helpful? Give feedback.
-
|
You seem to be coming from a text templating language. It converts text to other text based on interpolation. Any text can be interpolated anywhere in the document, because the content doesn’t have semantic meaning to the templating engine. MDX is a programming language that gets compiled to JavaScript. It has certain rules of what is valid syntax, and where JavaScript expressions are allowed. You can write dynamic links for instance in MDX, but you’ll have to use JSX syntax for that, not interpolation: {/* This is a link to { props.link } */}
[Click me]({ props.link })
{/* This is a link to whatever link is passed as the link prop */}
<a href={props.link}>Click me</a>Likewise, code blocks can’t be interpolated. However, you can use JSX and string expressions. <pre><code>{`Hello ${props.name}`}</code></pre>MDX supports plugins that can transform the code, similar to Babel. You later told us the variables are defined in frontmatter. The frontmatter data can be accessed using the <pre><code>{`Hello ${frontmatter.name}`}</code></pre>Alternatively you can access the frontmatter data in your own remark plugin (this also depends on import { Code, Root } from 'mdast'
import { Plugin, Transformer } from 'unified'
import { visit } from 'unist-util-visit'
import { parse } from 'yaml'
import { yourSubstitutionImplementation } from './some-module.js'
const remarkLiquid: Plugin<[], Root> = () => (ast) => {
const yaml = ast.children.find((child) => child.type === 'yaml')
if (!yaml) {
return
}
const frontmatter = parse(yaml.value)
visit(ast, 'code', (node: Code) => {
node.value = yourSubstitutionImplementation(node.value, frontmatter)
})
}
export default remarkLiquid;You can extend this to any node type you want, i.e. you could process links or inline code the same way. |
Beta Was this translation helpful? Give feedback.
-
This is the XY problem: https://meta.stackexchange.com/questions/66377/what-is-the-xy-problem/66378#66378. The overarching question you asked was about Liquid in code blocks, and then there were several smaller questions.
This might be better asked to the Docusaurus project. |
Beta Was this translation helpful? Give feedback.
-
|
@remcohaszing, I think that now I understand your proposal. It does not pre-process the entire file, as usual for Liquid, but only the code block content. For my use case this is probably enough and would allow to use most of the existing markdown without rewrites. Thank you very much! I selected your message as the answer. @wooorm, thank you for your patience. |
Beta Was this translation helpful? Give feedback.
-
|
Is using JSX still the answer as of today? It isn't practical to use JSX for any non-trivial code block (because I'd need to manually recreate all code highlighting tags). In principle, something like this would work: {/* SomeMarkdown.mdx */}
This is some MDX content.
```jsx
// Interpolated
console.log('Hello !{props.name}') // Displays: console.log('Hello John')
// console.log('Hello Alice')
// Not interpolated
console.log('Hello \!{props.name}') // Displays: console.log('Hello !{props.name}')
// Not interpolated
console.log('Hello \\!{props.name}') // Displays: console.log('Hello \!{props.name}')
```import SomeMarkdown from './SomeMarkdown.mdx'
Demo of passing parameters to code blocks.
<SomeMarkdown name="John" />
<SomeMarkdown name="Alice" />I feel like it's one of the last piece missing for MDX to be "conceptually perfect". |
Beta Was this translation helpful? Give feedback.
-
|
That example isn‘t dynamic so you don‘t need to do anything. It’s fine. And what does that transform to HTML? Do you think that transform could suddenly deal with dynamic runtime variables sent to the client? |
Beta Was this translation helpful? Give feedback.
-
Precisely, that's what I'm trying: being able to pass props to code blocks. This MDX code block is duplicated quite a lot across the
And it's only one of many examples. Being able to pass parameters to code blocks is something I see myself regularly wishing I could do.
I don't know much about how MDX works, but I guess that code blocks (and MDX in general) are transformed to JSX so I'm assuming that it should, in general, be possible to define JSX in code blocks. In this cass |
Beta Was this translation helpful? Give feedback.
-
|
You link to three different code blocks. I don’t understand what you want me to see.
Can you please show these actual use cases that you have?
You can indeed define JSX in things, when you use JSX to make that code block. See: https://github.com/orgs/mdx-js/discussions/2288#discussioncomment-10202606. What you are missing, is that often code blocks are used to talk about code, which includes Additionally, you implicitly talk about different tools, namely syntax highlighters. |
Beta Was this translation helpful? Give feedback.
-
Ah, indeed, these three code blocks have a lot of differences. Actually, I want to minimize the differences and have these code blocks be almost the same while using a code block parameter. In other words, it would be great if I could replace this: export { onBeforeRender }
import type { OnBeforeRenderAsync } from 'vike/types'
export const onBeforeRender: OnBeforeRenderAsync = async (
pageContext
): ReturnType<OnBeforeRenderAsync> => {
// ...
}With that: - export { onBeforeRender }
+ export { !{props.hookName} }
- import type { OnBeforeRenderAsync } from 'vike/types'
+ import type { !{capitalize(props.hookName) + 'Async' } from 'vike/types'
- export const onBeforeRender: OnBeforeRenderAsync = async (
+ export const !{props.hookName}: !{capitalize(props.hookName) + 'Async'} = async (
pageContext
- ): ReturnType<OnBeforeRenderAsync> => {
+ ): ReturnType<!{capitalize(props.hookName) + 'Async' }> => {
// ...
}So that I can re-use the same code block for all these pages.
Yes it would be nice to have a syntax that doesn't conflict too much. In the JavaScript world I don't foresee much conflicts with this syntax (using
I ain't familiar with how these tools work with each other so, yea, I don't know whether it's possible in practice. |
Beta Was this translation helpful? Give feedback.
-
These words you use: this is supsicously close to something JSX allows and frameworks provide: Components! export function MyReusableCodeSnippet(props) {
return <pre><code>{`export { ${props.hookName} }
import type { ${capitalize(props.hookName) + 'Async' } from 'vike/types'
export const ${props.hookName}: ${capitalize(props.hookName) + 'Async'} = async (
pageContext
): ReturnType<${capitalize(props.hookName) + 'Async'}> => {
// ...
}
`}</code></pre>
}You can then use that in your MDX: <MyReusableCodeSnippet hookName={'alpha'} />
I think you’re too focussed on one particular solution that you have in your mind now. |
Beta Was this translation helpful? Give feedback.
-
|
FYI, I finally took some time and started to convert my websites to Docusaurus. The resulting code looks like this: Basically most of the code blocks were rewritten to Quite a lot of work... :-( The only good news is that I managed to organise the code as a template (a Liquid template!) that I instantiate to generate the common code for all 20+ sites, thus making maintaining all those sites less frightening. |
Beta Was this translation helpful? Give feedback.
You seem to be coming from a text templating language. It converts text to other text based on interpolation. Any text can be interpolated anywhere in the document, because the content doesn’t have semantic meaning to the templating engine.
MDX is a programming language that gets compiled to JavaScript. It has certain rules of what is valid syntax, and where JavaScript expressions are allowed.
You can write dynamic links for instance in MDX, but you’ll have to use JSX syntax for that, not interpolation:
Likewise, code blo…