Re:Markdoc: Stripe's Markdown-based authoring framework
by tdrhq on Friday May 13, 2022 @01:05PM
(#31370100)
Quick question. How do engineers and tech writers use the "live editor" functionality that seems to be in the open source repo? Do you edit in the live editor and is it set up to update the underlying repo? Or do you just modify the markdoc files in the repo with your own editor?
Re:Markdoc: Stripe's Markdown-based authoring framework
by nukemandan on Wednesday May 11, 2022 @11:33PM
(#31348987)
I am a huge fan of this style of page! is there an OSS example of this in full? I would be very keen to see what goes into making such a dynamic page in markdoc looks like
Re:Markdoc: Stripe's Markdown-based authoring framework
by pomber on Thursday May 12, 2022 @06:12AM
(#31351706)
Not Markdoc, but there are several OSS examples of how you can do something similar with MDX + Code Hike. https://codehike.org/
Before we built Markdoc, our documentation was powered by ERB (embedded Ruby templates). Having content mixed with arbitrary code made it incredibly hard to reason about either. Because Markdoc is a declarative language rather than imperative, there's no intermediate state to keep track of, making things easier to follow.
At Stripe, both engineers and tech writers contribute to documentation. Markdoc makes things easier for everyone by keeping the content separate from the code, while still making it possible to build more interactive experiences when you want to. (For example, our integration builder [0] is also powered by Markdoc.)
[0] https://stripe.com/docs/payments/quickstart