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

91–100 of 157 posts

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

#91

Post by euroderf »

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…

Do all your extensions to Commonmark enable you to generate semantic HTML/XML that can be processed further down a pipeline with XSLT ? Or is the system used mainly to generate fairly standard HTML ? I'm thinking DITA here.

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

#93

Post by euroderf »

IshKebab wrote: post #57
dragonsh wrote: post #29

Good for people who like to work with non-standard markdown. Not sure why companies do not use RestructuredText (rst), which is a proper specification [0] and has been very successful in the area of documentation. In order to generate a print quality documentation from this markdoc format will be a huge task. RestructuredText already has strong support for Latex output. Now people have plain markdown, gitbook and now…

I've used RestructuredText quite extensively (my company uses it). I can see why people do not want to use it. 1. The specification for the syntax is decent but not really comprehensive. There's zero chance you could write a compatible implementation from it. To be fair this is true for the original Markdown but I think there's been a lot of effort to make fully defined versions (e.g. CommonMark), but... 2. The only…

Several previous discussions at HN have suggested that AsciiDoc is better to work with than RST.

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

#94

Post by uvesten »

bww wrote: post #49

Shameless plug: for REST APIs, I've written a tool called Instaunit which combines HTTP API integration tests with documentation generation, since these two things must always be maintained in lockstep. It's got a ways to go before it generates output that looks as good as Stripe's documentation, but it makes it dead simple to create API documentation that's guaranteed to be in sync with your service, because it was…

Looks neat!

The documentation does not seem to have any examples of the generated docs, though. I think that would be a good addition, because it’s a good selling point for the project.

(I.e I don’t think I’d go through downloading and running it just to see if the generated documentation is ”good enough”.)

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

#97

Post by Duhck »

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!

We use Remark, and given the ability to leverage AST, its pretty much limitless in terms of customization

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

#98

Post by SneakyTornado29 »

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!

Wow! Was thinking of doing the same because I wanted to include custom HTML elements suck as boxed block quotes in my Markdown documents. So does this solve the problem?

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

#99

Post by schemescape »

Are relative links supported?

The landing page uses root-relative links and the FAQ/examples don't seem to cover links in depth.

I like relative links because my editor (VS Code) will auto-complete relative links... but many Markdown-based tools don't handle the Markdown-source-to-output-HTML translation.

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

#100

Post by nkohari »

9dev wrote: post #88
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 :)

The Stripe docs use a library of a few dozen Markdoc tags. While the tags are different, the articles on https://markdoc.io are pretty similar to those in the Stripe docs. For example: https://raw.githubusercontent.com/markdoc/docs/main/pages/do...
Post reply on HN