[dead]
Markdoc: Stripe's Markdown-based authoring framework
101–110 of 157 posts
Re: Markdoc: Stripe's Markdown-based authoring framework
#102How does this compare to DocFX? One thing I think Microsoft does very well is the Azure documentation. It's consistently structured across services, but even better, it's also all just a bunch of Markdown and for any page, you can open a Github issue right from that page. And because it's in Github, you can see the history of a page, which has been helpful to see when options change or when limitations were clarified.
I think MSFT just uses stock DocFX for the Azure docs site, but I'm not sure.
Re: Markdoc: Stripe's Markdown-based authoring framework
#103I'm a bit confused. Following the React tutorials https://markdoc.io/docs/render#react I was able to render my own react components on custom tags, which I wanted. Nice! But I'm not being able to define how to render my own components for Markdown tags like paragraph or heading :(
Re: Markdoc: Stripe's Markdown-based authoring framework
#104Earlier quoted context omitted.
They explain the difference in an FAQ. https://markdoc.io/docs/faq > The key difference is that MDX supports arbitrarily-complex JavaScript logic (think: docs as code) while Markdoc enforces a strict separation between code and content (think: docs as data). > Markdoc uses a fully declarative approach to composition and flow control, where MDX relies on JavaScript and React. This means MDX affords users more power an…
Just a gentle reminder that docs like code has an actual definition that we can refer to. When we say treat the docs like code, we mean that you: * Store the doc source files in a version control system. * Build the doc artifacts automatically. * Ensure that a trusted set of reviewers meticulously review the docs. * Publish the artifacts without much human intervention. Docs Like Code, Anne Gentle, p. 10
The quoted text says "as" and clearly intends that meaning.
Re: Markdoc: Stripe's Markdown-based authoring framework
#105[dead]
From a quick glanze it could've been implemented with remark instead of patching markdown-it.
Re: Markdoc: Stripe's Markdown-based authoring framework
#106One 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…
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…
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 :-)
Re: Markdoc: Stripe's Markdown-based authoring framework
#107We get to use Markdoc every day and it is a joy to work with. Shameless plug: we're looking for someone to come in and a product manager over the Stripe Docs. Imagine working on docs at the company known for docs. Very fun problems. https://stripe.com/jobs/listing/product-manager-docs/3928998
Thanks for posting this. What is a good way for learning about the salary and compensation for this position? Nothing specific, b it just ballpark to determine if there’s basic compatibility before applying.
The title is too specific to get good numbers from googling and I worry that docs product managers wouldn’t make what typical product managers make. [0]
[0] https://www.glassdoor.com/Salary/Stripe-Product-Manager-Sala...
Re: Markdoc: Stripe's Markdown-based authoring framework
#108I'm a bit confused. Following the React tutorials https://markdoc.io/docs/render#react I was able to render my own react components on custom tags, which I wanted. Nice! But I'm not being able to define how to render my own components for Markdown tags like paragraph or heading :(
This is possible! Check out https://markdoc.io/docs/nodes#customizing-markdoc-nodes
Re: Markdoc: Stripe's Markdown-based authoring framework
#109OMG. I was just about to start my own Markdown parser because I needed custom elements and I was finding too hard to work with existing "customizable" Markdown parsers. Also, I needed a React renderer for React-Native and I was also about to write my own. By the looks of it, I will be able to just use Markdoc. Thank you Stripe!
Hey, if you really want to customize markdown with your own elements and their rendering/templating, check out SGML [1]. It's made for exactly this type of flexible and extensible document apps/sites, even allows custom Wiki syntax rules.
[1]: http://sgmljs.net
Re: Markdoc: Stripe's Markdown-based authoring framework
#110Earlier quoted context omitted.
What powers the API docs ?
It's all custom; the frontend is React and the backend is Ruby. Our plan is to introduce Markdoc as an intermediary step to improve the authoring experience.
Just to add to that, "normal" markdown (I forget which flavor exactly) is currently used for the text blocks within the Stripe API reference documentation.