Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Markdoc: Stripe's Markdown-based authoring framework

markdoc.io

Post reply on HN
Print view View original

131–140 of 157 posts

Re: Markdoc: Stripe's Markdown-based authoring framework

#131

Post by eek2121 »

cdevroe wrote: post #34
oellegaard wrote: post #32

Earlier quoted context omitted.

Would be very cool with some information on how they work with creating the docs, manage them etc.

I agree. Most companies, open source projects, and individual developers find this to be a Herculean challenge. I'd love to know if Stripe has any secrets to keeping their Docs updated. Though, my gut says that they likely just put in the work. Their Docs are incredibly important to their success.

I would describe stripe docs as 'acceptable'. Don't get me wrong, I personally have brought them tons of business and work with their API more than a human should. My only issue is that if you are working with their API, you will discover HUGE gaps if you step outside "the norms". That being said, they are a step above everyone else, which should tell you something. Also, the comment regarding open-source applies 300%.

Re: Markdoc: Stripe's Markdown-based authoring framework

#132

Post by DrewADesign »

jb3689 wrote: post #75
cdevroe wrote: post #34

Earlier quoted context omitted.

I agree. Most companies, open source projects, and individual developers find this to be a Herculean challenge. I'd love to know if Stripe has any secrets to keeping their Docs updated. Though, my gut says that they likely just put in the work. Their Docs are incredibly important to their success.

It helps when you have people staffed full time for the work. Stripe views docs as a product, not an afterthought

They also treat docs as a way to add detail to and flesh out well-designed products rather than as a way to disclaim and explain things they didn’t feel like or have the resources to fix.

Re: Markdoc: Stripe's Markdown-based authoring framework

#133

Post by riwsky »

data_ders wrote: post #76
segphault wrote: post #46

Earlier quoted context omitted.

Hey, I work on the Docs Product engineering team at Stripe and created Markdoc. The scope is somewhat different: Jekyll and Middleman are static site generators that provide a full stack for content publishing whereas Markdoc is a framework for processing Markdown content with custom tags and transforming it into the desired output format. Markdoc can be used inside of a static site generator or a custom documentatio…

way cool! I work at dbt Labs and see a similarity with dbt jinja, where all dbt does is render the jinja tags into "pure" SQL. is this the same thing in that markdoc "compiles" markdoc files into markdown, that then can be used in static-site generators?

It’s not. dbt goes out of its way to avoid having to parse SQL into an ast; Markdoc is Stripe going out of its way to parse input to an ast. dbt’s approach is more similar to the ERB system Stripe mentions Markdoc replacing.

Re: Markdoc: Stripe's Markdown-based authoring framework

#134

Post by nukemandan »

nkohari wrote: post #38
ipsum2 wrote: post #16

Earlier quoted context omitted.

> Markdoc uses a fully declarative approach to composition and flow control, where MDX relies on JavaScript and React. This doesn't make sense to me? React is also a "fully declarative approach to composition and flow control". > content can quickly become as complex as regular code Okay, but has that actually happened in practice?

> Okay, but has that actually happened in practice? 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 c…

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

#135

Post by __mharrison__ »

jtbayly wrote: post #130
__mharrison__ wrote: post #120

Earlier quoted context omitted.

A few folks recommended Quarto to me when I asked about current recommendations recently. My main goal is physical books and that doesn't seem to be a first class citizen anywhere. Looking through Quarto, I can't find reference to markdown syntax for index entries (which indicates that they don't support it.) Also, I'm heavily biased, but based on my experience I will need to hack whatever tool and I'm not really int…

Bookdown seems to support index entries: https://bookdown.org/yihui/bookdown/latex-index.html I wouldn't be surprised if Quarto supports the same syntax, since they are related. But it is possible it doesn't.

It might. I'm not interested in hacking R.

Re: Markdoc: Stripe's Markdown-based authoring framework

#137

Post by fastball »

andrerpena wrote: post #86

OMG. 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!

For my startup, which is built around Markdown notecards[1], we've been using markdown-it, which it seems is also being leveraged by the Markdoc project. So far I've written a couple of extensions for markdown-it and haven't really had any issues.

[1] https://supernotes.app

Re: Markdoc: Stripe's Markdown-based authoring framework

#138

Post by todd3834 »

So it’s been a few hours and I really love this library! I integrated it into a React/esbuild application and it is working great. The React/Prism example for code highlighting took a little work. They have an example but it is a little buried. Their example wasn’t working for me but it was enough for me to get my own working without react-prism.

Shameless plug: If anyone is interested, I published my esbuild plugin so you don’t have to transform on the server if you want to just import a markdown file.

https://github.com/toddw/esbuild-markdoc-plugin

Re: Markdoc: Stripe's Markdown-based authoring framework

#139

Post by Abishek_Muthian »

cdevroe wrote: post #26

Stripe's Docs have been best-in-class for a long time. Obviously, the care and human hours they put into their upkeep is the main reason for the Docs being so good. But, as with any creative endeavor, the tools matter. If the Stripe team didn't like the content management system they used to keep the Docs up-to-date they'd be less likely to do it. As someone that has used their Docs for hours and hours and hours I'm…

Unfortunately my experience has been different; I found that Stripe's Go doc doesn't match their API and while searching on it I found that someone else had mentioned that to their personnel over freenode 2 years ago.

So I raised an issue on GitHub[1] on Apr 9 and hasn't been attended to yet.

On a more serious note, Stripe's payment links doc seemed to imply that tax rates are automatically calculated if the tax rates are set(as we do with code when we pass the tax_id), But I found after couple of payments that tax aren't being charged, On conversing on Twitter with the payment links dev I came to realize that the required option was not there for me[2] and then after couple of hours with their support staff I was informed that the options was not available for India as 'Stripe Tax' is a separate product.

Overall, I'm happy with Stripe's tech; at least compared to the other options I have. But their docs have caused me some frustrations.

[1] https://github.com/stripe/stripe-go/issues/1447

[2] https://twitter.com/joshuaackerman/status/144759582096702259...

Post reply on HN