Hacker News Re-Imagined

Markdoc: Stripe's Markdown-based authoring framework

  • 810 points
  • 12 days ago

  • @colinclerk
  • Created a post

Markdoc: Stripe's Markdown-based authoring framework


@data_ders 12 days

Replying to @colinclerk 🎙

is this jinja? the {% %} makes it look like jinja to me?

Reply


@majkinetor 12 days

Replying to @colinclerk 🎙

I am glad to know there are those that put so much thought into documentation. Documentations is just another service, and deserves all the same methodology: CI/CD, automatic tests, components and reuse, different environments etc.

As far as I can see, you can get similar workflow with combination of existing tools. I created this docker image that combines them for very easy consumption and created thousands of pages of technical, functional and user documentation with it:

https://github.com/majkinetor/mm-docs

Reply


@dragonwriter 12 days

Replying to @colinclerk 🎙



@_miau_hoch2 12 days

Replying to @colinclerk 🎙

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

Reply


@meshaneian 12 days

Replying to @colinclerk 🎙

Solid competitor to https://hackmd.io/ (codimd on github)

Reply


@creakingstairs 12 days

Replying to @colinclerk 🎙

I’ve been writing a similar thing for my blog. I wish I came across this sooner as this looks like exactly what I had wanted.

Reply


@schemescape 12 days

Replying to @colinclerk 🎙

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.

Reply


@polutropos 12 days

Replying to @colinclerk 🎙

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?

Reply


@alphang 12 days

Replying to @colinclerk 🎙

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.

Reply


@etchalon 12 days

Replying to @colinclerk 🎙

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

Reply


@nik736 12 days

Replying to @colinclerk 🎙

Browsing their Docs has this weird, glitchy animation. Where is it coming from?

Reply


@bww 12 days

Replying to @colinclerk 🎙

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

Reply


@AtNightWeCode 12 days

Replying to @colinclerk 🎙

I have been looking for exactly this. Will test it out for sure.

On a side-note, mixing serifs and sans in the way the site does looks like something only a mass murderer would do.

Reply


@fellowniusmonk 12 days

Replying to @colinclerk 🎙

"side-by-side" is a module that seems to be used extensively throughout this projects documentation, as well as in stripes documentation. I don't see where it is defined anywhere, do they have a library of these common helpers? I looked but I guess my searchfu isn't what it used to be.

Reply


@gambler 12 days

Replying to @colinclerk 🎙



@blutack 12 days

Replying to @colinclerk 🎙

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 web UI/editor built into the binary. Oh, and if it could manage multiple documents and versioning that would be great too. Looking for a Fossil SCM kind of feel?

Closest thing I've used would probably be LyX but that's almost too capable!

I do appreciate this is a really hard thing to do and I'm wondering what toolchains other people are using?

Reply


@cercatrova 12 days

Replying to @colinclerk 🎙

Lol, I haven't seen the text following the mouse cursor ("Try it out") in a long time. Glad to see some whimsy is still present on the Internet.

Reply


@ABraidotti 12 days

Replying to @colinclerk 🎙

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?

Reply


@zellyn 12 days

Replying to @colinclerk 🎙

One curiosity: I was trying to figure out how the diagram at the top of https://markdoc.io/docs/render was generated.

The items inside the diagram seem curiously absent from the source of the page: https://raw.githubusercontent.com/markdoc/docs/main/pages/do...

Instead, when the `diagram` tag is defined, it maps the "type" parameter to a particular diagram: https://github.com/markdoc/docs/blob/main/components/Diagram...

Any reason it is done that way, rather than specifying the diagram in the source of the document using mermaid, pikchr, etc? Even inlining the SVG seems like it would be better for keeping everything together.

Reply


@dallasgutauckis 12 days

Replying to @colinclerk 🎙

Add a newline after the title frontmatter and type "u"

Reply


@inson 12 days

Replying to @colinclerk 🎙

Is this a new type of Jinja?

Reply


@todd3834 11 days

Replying to @colinclerk 🎙

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

Reply


@seanwilson 12 days

Replying to @colinclerk 🎙

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.

Reply


@andrerpena 12 days

Replying to @colinclerk 🎙

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!

Reply


@IshKebab 12 days

Replying to @colinclerk 🎙

This looks nice but you might want to have an example of the custom syntax on the front page because as far as I can tell that is the main thing this adds, and currently the front page doesn't make it sound different to anything else.

Reply


@mikelabatt 12 days

Replying to @colinclerk 🎙

It was good to read "Why not AsciiDoc?" in their FAQ: https://markdoc.io/docs/faq

Reply


@openbrian 12 days

Replying to @colinclerk 🎙

See also HedgeDoc https://hedgedoc.org/ which is collaborative and supports tables.

Reply


@bkrishnan 12 days

Replying to @colinclerk 🎙

As someone who was about to use Remark (https://github.com/remarkjs/remark) and Next.js to start a new blog, does this solve something that Remark doesn't? Genuinely curious.

Reply


@cdevroe 12 days

Replying to @colinclerk 🎙

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 thankful to their team for how good their Docs are.

Very cool of them to open source this. Looks great.

Reply


@ksajadi 12 days

Replying to @colinclerk 🎙

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?

Reply


@epaulson 12 days

Replying to @colinclerk 🎙

How does this compare to DocFX? One thing I think Microsoft does very well is the Azure documentation. It's consistently structured across services, but even better, it's also all just a bunch of Markdown and for any page, you can open a Github issue right from that page. And because it's in Github, you can see the history of a page, which has been helpful to see when options change or when limitations were clarified.

I think MSFT just uses stock DocFX for the Azure docs site, but I'm not sure.

Reply


@andrerpena 12 days

Replying to @colinclerk 🎙

I'm a bit confused. Following the React tutorials https://markdoc.io/docs/render#react I was able to render my own react components on custom tags, which I wanted. Nice! But I'm not being able to define how to render my own components for Markdown tags like paragraph or heading :(

Reply


@alberth 12 days

Replying to @colinclerk 🎙

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)

Reply


@dragonsh 12 days

Replying to @colinclerk 🎙

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 markdoc with its own set of non standard extensions. Hopefully rst format can catch up among JavaScript developers.

So far haven’t seen a complete documentation tool like Python Sphinx [1].

[0] https://docutils.sourceforge.io/docs/ref/rst/restructuredtex...

[1] https://www.sphinx-doc.org/en/master/

Reply


@fedeb95 12 days

Replying to @colinclerk 🎙

the pointer is annoying though

Reply


@d4rkp4ttern 10 days

Replying to @colinclerk 🎙

Does this have functionality to auto-generate docs from (python) docstrings? Currently using Sphinx with RTD (ReadTheDocs) theme for this, and quite happy with it, though the setup took a lot of hunting around for examples. Wondering if this is the best auto-doc approach for python these days. For context, I am developing a code base with the intention of later open sourcing it, so wanted to have it properly documented from the start.

Reply


@oellegaard 12 days

Replying to @colinclerk 🎙

It looks like a static site generator - but at the same time it appears you cannot actually generate a static site from it, but you need to run a node.js server.

What separates this from any of the existing markdown static site generators?

Reply


@lordleft 12 days

Replying to @colinclerk 🎙

This is an almost breathtaking documentation site.

Reply


@annagrigoryan2 11 days

Replying to @colinclerk 🎙

Found this right when I was looking for a quality markdown parser.

I guess it's my lucky day.

Reply


@aquilaFiera 12 days

Replying to @colinclerk 🎙

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

Reply


About Us

site design / logo © 2022 Box Piper