News for hackers. Stuff that matters.
Re:Interactive Docs with Markdoc by m_ke on Thursday September 15, 2022 @04:04PM (#32857752)
Should probably mention mdx since it's a much better alternative that has been available for a while
Re:Interactive Docs with Markdoc by nkohari on Thursday September 15, 2022 @04:36PM (#32858112)
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

Re:Interactive Docs with Markdoc by ipsum2 on Thursday September 15, 2022 @06:20PM (#32859180)
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 %}

?
Re:Interactive Docs with Markdoc by tolmasky on Thursday September 15, 2022 @07:15PM (#32859711)
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.

Re:Interactive Docs with Markdoc by wahern on Thursday September 15, 2022 @09:03PM (#32860676)
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.
Re:Interactive Docs with Markdoc by russellbeattie on Thursday September 15, 2022 @07:24PM (#32859814)
I didn't see this until after I posted a similar example. Yes, I agree 100%.
Re:Interactive Docs with Markdoc by dsmmcken on Thursday September 15, 2022 @05:18PM (#32858582)
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.
Re:Interactive Docs with Markdoc by djbusby on Thursday September 15, 2022 @11:20PM (#32861686)
Any pointers to code you could share?
Re:Interactive Docs with Markdoc by uhryks on Thursday September 15, 2022 @05:11PM (#32858519)
Chase McCoy had a good note explaining it: 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.

Re:Interactive Docs with Markdoc by lucasyvas on Thursday September 15, 2022 @08:10PM (#32860241)
Oh man, are we swinging back the other way again? lol
Re:Interactive Docs with Markdoc by fastball on Friday September 16, 2022 @12:23AM (#32862052)
Which docs are built with MDX that you prefer to the docs at Stripe?