[HN Gopher] Interactive Docs with Markdoc
___________________________________________________________________
Interactive Docs with Markdoc
Author : tomger
Score : 53 points
Date : 2022-09-14 11:36 UTC (1 days ago)
(HTM) web link (stripe.com)
(TXT) w3m dump (stripe.com)
| jph wrote:
| Markdoc syntax and capability looks so much like MDX
| (https://mdxjs.com). Can anyone who's evaluated Markdoc and MDX 2
| comment?
|
| I'm currently doing an architecture decision record about
| Markdown documentation, and will add Markdoc to the candidates.
| The leaders so far are MDX 2 with plugins for JSX-style work, and
| Svelte for a fully dynamic site.
|
| I'm aware of the Markdoc page about "Why not MDX?" which explains
| that Markdoc is deliberately less capable than MDX. But the page
| doesn't show how to do typical needs (IMHO) such as loops or
| substitutions. And for simple writing, compare with standard
| markdown annotated with tags/templates using Liquid or Jinja or
| similar?
| drx wrote:
| Really cool of @koomen to donate the domain, from the github repo
| (https://github.com/markdoc/markdoc): Special
| shout out to: @marcioAlmada for providing us with the
| @markdoc GitHub org. @koomen for gifting us
| https://markdoc.dev.
| behnamoh wrote:
| Interesting to see another post on HN frontpage about Stripe's
| "incompetent" review team, and then see this one.
| atonse wrote:
| We're using markdown + liquid with custom liquid tags.
|
| This looks so similar to that.
| segphault wrote:
| Hey, I'm the creator of Markdoc and the author of that blog
| post.
|
| The key advantage of using Markdoc instead of using Markdown
| with liquid or another string-based templating system that
| preprocess the content is that the tags and other custom syntax
| are a first-class part of the Markdoc format. The document
| parses to an AST and the individual tags can programmatically
| manipulate the content and document node hierarchy instead of
| just manipulating or outputting strings of text that are passed
| on to a Markdown processor.
| jph wrote:
| You may have misunderstood the parent post? Custom Liquid
| tags use code that can do anything you want: programmatically
| manipulate content, read databases, invoke APIs, autogenerate
| examples, run tests, use git, etc.
| chipotle_coyote wrote:
| No, Segphault literally addressed why Markdown with Liquid
| is not the same as Markdoc on a processing level. "Custom
| tags processed by [thing that is not Markdown]" !=
| "Markdown superset that makes custom tags first-class
| entities". Either your template processor is run before the
| Markdown processor and outputs Markdown, or it's run after
| the Markdown processor and outputs HTML. Neither one is
| doing what Markdoc is doing. Markdoc parses to an AST;
| "Markdown + [other thing]" does not. The difference may be
| immaterial in some use cases, including yours, but it's
| still a difference.
| m_ke wrote:
| Should probably mention mdx since it's a much better alternative
| that has been available for a while
| nkohari wrote:
| 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
| [deleted]
| ipsum2 wrote:
| 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 %} ?
| uhryks wrote:
| 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.
| dsmmcken wrote:
| 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.
___________________________________________________________________
(page generated 2022-09-15 23:00 UTC)