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

81–90 of 157 posts

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

#81

Post by etchalon »

Veen wrote: post #19
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?

No idea, but it's worth keeping in mind that documentation isn't always written and edited by developers (because developers aren't always good writers). Maintaining the separation between code and content is a good idea if a company uses technical writers or other non-developer content people.

We handle this by having some components that don't require much training to use (, , ).

I don't think you have to choose between "can be powerful" and "can be simple."

If you want to lock things down so no one EVER puts code in your docs, Markdoc looks great.

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

#82

Post by seanwilson »

How well does this scale to hundreds of pages? I found Jekyll and others can start to slow down here during page generation where it can take several seconds to generate not that many pages, especially if you're using a lot of template features. It's part of the reason Hugo is my default as it's so fast.

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

#83

Post by bccdee »

segphault wrote: post #46
ksajadi wrote: post #7

I'm not sure what the difference is between this and a bunch of other ones like Jekyll or Middleman? Is it in the render phase? What am I missing?

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…

What are the advantages of integrating templating and markdown like that? If I'm using markdown with nunjucks, for instance, what do I stand to gain from switching to Markdoc?

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

#85

Post by armchairhacker »

_miau_hoch2 wrote: post #64

For anyone looking for a doc generation tool: I was lately evaluating several tools like VuePress, Docusaurus and AsciiDoc. I ended up using Mkdocs Material ( https://squidfunk.github.io/mkdocs-material/ ). If you haven't already, have a look. I think it is pretty impressive. From tags, tabs to the fantastic built-in search ...

After looking through Docusaurus, GitBook, and a few others, I also ended up with mkdocs and github pages. It’s very straightforward to setup.

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

#86

Post by andrerpena »

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!

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

#87

Post by kposehn »

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!

I was in the same boat, wanting to migrate away from Jekyll+Liquid. Very glad they released this.

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

#88

Post by 9dev »

aquilaFiera wrote: post #78

We 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

I’m curious how much you’ve actually customised it. Does the docs source still have a resemblance to markdown, or is it more of a react-like DSL by now?

Job sounds super fun by the way :)

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

#89

Post by alphang »

From the docs, it looks like they're emphasizing the document format part, and less so the authoring system (which would make me think of SSG/CI/etc).

It also looks like there are functions, but they're considerably shaved down compared to JavaScript/etc.

I wonder if this will get more adoption in the TW community and by various static site generators.

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

#90

Post by cdevroe »

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

Totally agree. There are other companies, though, that have people staffed for the work and they do not do nearly as good of a job. I shall refrain from naming names. :)
Post reply on HN