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

61–70 of 157 posts

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

#61

Post by bbkane »

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…

Typora includes diagram supports and export to PDF. It costs $15 with a free trial, but it's worth every penny.

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

#62

Post by wolframhempel »

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…

Totally agree. What makes Stripe's docs so great is not just the content, but also the structure and embedded functionality. Switching between programming languages is seamless, the examples are pre-populated with data from my stripe account which is immediately meaningful to me.

Any framework that supports this functionality is a great contribution to OS

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

#63

Post by vvram »

nkohari wrote: post #50
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.

What powers the API docs ?

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

#64

Post by _miau_hoch2 »

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

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

#65

Post by verdverm »

harg wrote: post #48
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 a…

you definitely need something around this, it lacks a lot of the other features in Hugo or Jekyll

Might be easier to graft into an existing, dynamic CMS (that uses a DB)

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

#66

Post by docmechanic »

Veen wrote: post #5
etchalon wrote: post #2

I don't understand how this is fundamentally different than MDX, which can already mix React components within Markdown. We used it to build the Streamlit docs. I assumed this is how everyone was doing documentation: https://github.com/streamlit/docs

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

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

#67

Post by docmechanic »

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.

An alternative point of view from Docs Like Code, p.11

Reasons we treat docs like code

Coders and writers have borrowed tools and techniques from each other for decades. When you look at the history of producing docs and code together, you see that tools were invented specifically to produce docs while coding.

For example, the JavaDoc tool has been available since the first Java release in 1999. Visualizing the code in HTML, providing accessible online docs, and updating the documentation with the code were all keys to its success.

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

#68

Post by slorber »

ABraidotti wrote: post #51

I've been thinking about using this or Docusaurus to start a blog. Does anyone have an opinion on which of the two is better/easier/etc?

I don't know about Markdoc but with Docusaurus you can have your blog in 1min, just go to docusaurus.new

(I'm the maintainer)

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

#69

Post by droopyEyelids »

threepio wrote: post #55
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.

As an individual developer with many open-source projects, I'm pretty sure that my docs would be better if I had $2+ billion in funding ;)

The odds are deeply against your assertion- If we look at companies with $2b in funding, chances are yours would fall somewhere in the the median range, rather than at the top of the pack.

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

#70

Post by robertlagrant »

threepio wrote: post #55
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.

As an individual developer with many open-source projects, I'm pretty sure that my docs would be better if I had $2+ billion in funding ;)

Maybe you'd have $2+ billion in funding if your docs were better!
Post reply on HN