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

41–50 of 157 posts

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

#41

Post by geokon »

blutack wrote: post #23

Does anyone know of tooling like this but not for only making websites? I have an asciidoc based chain that mostly works for generating both PDF manuals and standalone html docs but it's a bit of a faff to install and set up especially for non-technical users. My dream is something like pandoc but with one or more diagram libraries integrated, native PDF output and all wrapped up in a single binary, maybe with a nice…

I got kinda intimidated with the Asciidoc toolchain that I instead just wrote a bit of Clojure to call the Java AsciidocJ API. A tiny script that did what I want (make Reveal slides) and it's simple/straightforward and I guess crossplatform :)

So better than even a command line thing

If you want a GUI then I'm guessing AsciidocFx

https://github.com/asciidocfx/AsciidocFX

(haven't tried it myself)

There is also Orgmode and Texmacs - but I don't really like that the markup is kinda "locked" to an editor. For instance I've done stuff with Orgmode for ages, but it breaks between Emacs major versions and you can't really export it without having Emacs. I also feel like I'm in effect locked into the platform

Texmacs actually looks fantastic, but I'm nervous putting all my beans in that basket

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

#42

Post by uneekname »

blutack wrote: post #23

Does anyone know of tooling like this but not for only making websites? I have an asciidoc based chain that mostly works for generating both PDF manuals and standalone html docs but it's a bit of a faff to install and set up especially for non-technical users. My dream is something like pandoc but with one or more diagram libraries integrated, native PDF output and all wrapped up in a single binary, maybe with a nice…

Pandoc filters and templates can be used to create complex, replicable workflows like this.

If you want to generate diagrams using pandoc, there are filters that will do that for you.

I dream of a UI for authoring pandoc ASTs ... someday I'll sit down and make it!

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

#43

Post by ericholscher »

cubes wrote: post #36
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 both Markdown and RST extensively. I feel RST has a steeper learning curve than Markdown, and that can be an obstacle to a successful documentation culture at an organization. As a former colleague liked to say, "The bar to authoring documentation needs to be so low you can trip over it."

The learning curve for RST is generally higher because it does more. You'll notice that Markdown's learning curve goes up quite a bit as they add all the features that RST has. That said, RST has some bad design decisions, but I'd say about 75% of the complexity it introduces is needed, and the 25% is bad design.

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

#44

Post by alberth »

So what's the workflow for this?

Because this seems to be run locally, vs something hosted like a CMS.

You locally have a NodeJS app running, you draft a new page, it renders it for you in HTML/CSS, and then you upload the rendered output to your web server?

(Sorry for the naive question)

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

#45

Post by zdw »

cubes wrote: post #36
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 both Markdown and RST extensively. I feel RST has a steeper learning curve than Markdown, and that can be an obstacle to a successful documentation culture at an organization. As a former colleague liked to say, "The bar to authoring documentation needs to be so low you can trip over it."

> As a former colleague liked to say, "The bar to authoring documentation needs to be so low you can trip over it."

Wikis have an incredibly low bar, and at some point making things easy leads directly to garbage-in-garbage-out disorganization.

Having docs go through the same linting and code review process (which should also be easy!) as code is the way forward for docs longer than a few pages.

Sphinx is excellent and batteries included for this sort of lint process.

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

#46

Post by segphault »

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 documentation platform.

Markdoc's syntax and custom tags also take a somewhat different approach than many of the string templating systems that are commonly used in static site generators. Markdoc is not a preprocessor, the tags are treated as a first-class part of the markdown content, which parses into a data structure that can be statically analyzed, programmatically transformed, and rendered into the desired output format. For us, that's React, but it could be raw HTML, Web Components, a slide deck, or whatever else you might come up with.

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

#48

Post by harg »

alberth wrote: post #44

So what's the workflow for this? Because this seems to be run locally, vs something hosted like a CMS. You locally have a NodeJS app running, you draft a new page, it renders it for you in HTML/CSS, and then you upload the rendered output to your web server? (Sorry for the naive question)

It would depend on the use case, but as this looks like it's aimed at a technical audience, you'd generally have some sort of CI/CD pipeline that renders the markdoc on a server and deploys the output accordingly, be it a react app, plain html, etc.

In many cases, authors would probably need to run the toolchain locally so they can preview their changes. But publishing would basically be the same as committing code and having a CI pipeline take it from there

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

#49

Post by bww »

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 generated by your tests when they ran.

https://github.com/instaunit/instaunit

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

#50

Post by nkohari »

polutropos wrote: post #47

This is amazing. Does this power the Stripe API reference pages? https://stripe.com/docs/api Or is this only for https://stripe.com/docs , https://stripe.com/docs/payments , etc?

Right now we're only using it in our narrative docs (http://stripe.com/docs) but we have plans to use it in the reference docs as well.
Post reply on HN