5 ms·

Can you say more about why you think MDX is better? For what it's worth, we considered MDX, but chose not to use it. Full explanation here: https://markdoc.dev

Can you say more about why you think MDX is better? For what it's worth, we considered MDX, but chose not to use it. Full explanation here: https://markdoc.dev/docs/faq#why-not-mdx https://markdoc.dev/docs/faq#why-not-mdx

deleted 4y ago
[deleted]
uhryks 4y ago
Chase McCoy had a good note explaining it: https://chasem.co/2022/05/markdoc https://chasem.co/2022/05/markdoc Basically because MDX mixes JSX and markdown, you need knowledge of JSX/JS (which non-devs might not have), and tooling dedicated to build, parse it and so on. Markdoc is more of a "separation of concerns" approach.
- lucasyvas 4y ago
  Oh man, are we swinging back the other way again? lol
dsmmcken 4y ago
I haven't experienced the supposed concern of complexity with MDX. I have a docs site with 1600+ md pages. In practice I've exposed a small number of react components that doc writers can use and that's it. Sure in theory they could introduce new complexity, but they don't. Further, you can introduce new markdown primitives with remark that get transformed to react components if you want to hide some of that complexity from writers. For example, we have one that auto collapses adjacent fenced code blocks of different language into one react component with a built in language switcher.
- djbusby 4y ago
  Any pointers to code you could share?
ipsum2 4y ago
Speaking for myself, I'm tired of learning yet another templating language re-implementing basic features like if, else, and for loops when I could just use an existing language with a few additions. Learning HTML is pretty easy, even for non-engineers. Doesn't this syntax: <callout type="check">...</callout> Look better than: {% callout type="check" %}...{% /callout %} ?
- tolmasky 4y ago
  I think the point is being able to then use markdown inside of that block, since many people seem to think that "**hello**" does look better than "<b>hello</b>". That being said, it would perhaps have been better to allow for HTML tags inside the markdown that themselves can have markdown inside of them (I'm not sure if this is the default behavior of markdown or not, or whether there are any weird parsing pitfalls in allowing this). I think that perhaps there is also a contingency of people that have been using templates for ages that have the "{% %}" style, so this is maybe attractive to those folks? To be clear, I agree with you, but I am just trying to figure out why this syntax would be chosen. Edit: Perhaps there is also some sort of HTML injection argument against using real tags? That is to say, if you have an interface that allows users to input markdown, then with "{% %}" you can easily filter the allowable template tags, but perhaps it is just more error prone to try to handle "<>" tags that might then themselves get inserted into live HTML. I haven't thought it all the way through but just wondering if there is a non-stylistic argument for it.
- russellbeattie 4y ago
  I didn't see this until after I posted a similar example. Yes, I agree 100%.
- wahern 4y ago
  ColdFusion fan? I still have a soft-spot for ColdFusion, even though like most other ColdFusion developers I moved on to both PHP and Java, and then to other pastures entirely. ColdFusion's embrace of Java spelled its demise, becoming lost in the swamp of enterprise complexity.

deleted 4y ago

[deleted]

uhryks 4y ago

Chase McCoy had a good note explaining it: https://chasem.co/2022/05/markdoc https://chasem.co/2022/05/markdoc Basically because MDX mixes JSX and markdown, you need knowledge of JSX/JS (which non-devs might not have), and tooling dedicated to build, parse it and so on. Markdoc is more of a "separation of concerns" approach.

lucasyvas 4y ago
Oh man, are we swinging back the other way again? lol

dsmmcken 4y ago

I haven't experienced the supposed concern of complexity with MDX. I have a docs site with 1600+ md pages. In practice I've exposed a small number of react components that doc writers can use and that's it. Sure in theory they could introduce new complexity, but they don't. Further, you can introduce new markdown primitives with remark that get transformed to react components if you want to hide some of that complexity from writers. For example, we have one that auto collapses adjacent fenced code blocks of different language into one react component with a built in language switcher.

djbusby 4y ago
Any pointers to code you could share?

ipsum2 4y ago

Speaking for myself, I'm tired of learning yet another templating language re-implementing basic features like if, else, and for loops when I could just use an existing language with a few additions. Learning HTML is pretty easy, even for non-engineers. Doesn't this syntax: <callout type="check">...</callout> Look better than: {% callout type="check" %}...{% /callout %} ?

tolmasky 4y ago
I think the point is being able to then use markdown inside of that block, since many people seem to think that "**hello**" does look better than "<b>hello</b>". That being said, it would perhaps have been better to allow for HTML tags inside the markdown that themselves can have markdown inside of them (I'm not sure if this is the default behavior of markdown or not, or whether there are any weird parsing pitfalls in allowing this). I think that perhaps there is also a contingency of people that have been using templates for ages that have the "{% %}" style, so this is maybe attractive to those folks? To be clear, I agree with you, but I am just trying to figure out why this syntax would be chosen. Edit: Perhaps there is also some sort of HTML injection argument against using real tags? That is to say, if you have an interface that allows users to input markdown, then with "{% %}" you can easily filter the allowable template tags, but perhaps it is just more error prone to try to handle "<>" tags that might then themselves get inserted into live HTML. I haven't thought it all the way through but just wondering if there is a non-stylistic argument for it.
russellbeattie 4y ago
I didn't see this until after I posted a similar example. Yes, I agree 100%.
wahern 4y ago
ColdFusion fan? I still have a soft-spot for ColdFusion, even though like most other ColdFusion developers I moved on to both PHP and Java, and then to other pastures entirely. ColdFusion's embrace of Java spelled its demise, becoming lost in the swamp of enterprise complexity.