News for hackers. Stuff that matters.
Re:Markdoc: Stripe's Markdown-based authoring framework by zellyn on Wednesday May 11, 2022 @12:58PM (#31342689)
One curiosity: I was trying to figure out how the diagram at the top of https://markdoc.io/docs/render was generated.

The items inside the diagram seem curiously absent from the source of the page: https://raw.githubusercontent.com/markdoc/docs/main/pages/do...

Instead, when the `diagram` tag is defined, it maps the "type" parameter to a particular diagram: https://github.com/markdoc/docs/blob/main/components/Diagram...

Any reason it is done that way, rather than specifying the diagram in the source of the document using mermaid, pikchr, etc? Even inlining the SVG seems like it would be better for keeping everything together.

Re:Markdoc: Stripe's Markdown-based authoring framework by mfix22 on Wednesday May 11, 2022 @01:04PM (#31342771)
Good question. You are right in that it is implemented as a mapping from type → SVG in the Markdoc docs site. However, diagrams don't need to be implemented this way.

In fact, on stripe.com/docs we use Markdoc + https://reactflow.dev to render custom diagrams (with translated content and everything). There is a good example of this in action on https://stripe.com/docs/payments/checkout/how-checkout-works, if you are curious.

Re:Markdoc: Stripe's Markdown-based authoring framework by zellyn on Wednesday May 11, 2022 @05:07PM (#31345778)
Interesting. Thanks for the reply. I'm trying to understand what it would be like to adopt Markdoc as our internal documentation system. I didn't like the "spooky action at a distance" of defining diagrams far away from the text, so I'm glad to hear it's not usual practice :-)