from Hacker News

Markdoc: Stripe's Markdown-based authoring framework

by colinclerk on 5/11/22, 3:07 PM with 146 comments

  • by cdevroe on 5/11/22, 4:14 PM

    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.

  • by aquilaFiera on 5/11/22, 6:22 PM

    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

  • by etchalon on 5/11/22, 3:24 PM

    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

  • by _miau_hoch2 on 5/11/22, 5:46 PM

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

  • by ksajadi on 5/11/22, 3:35 PM

    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?

  • by andrerpena on 5/11/22, 7:20 PM

    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!

  • by oellegaard on 5/11/22, 4:17 PM

    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?

  • by polutropos on 5/11/22, 4:53 PM

    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?

  • by alberth on 5/11/22, 4:49 PM

    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)

  • by todd3834 on 5/12/22, 6:13 AM

    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

  • by bww on 5/11/22, 4:55 PM

    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

  • by dragonsh on 5/11/22, 4:16 PM

    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/

  • by openbrian on 5/11/22, 6:16 PM

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

  • by blutack on 5/11/22, 4:06 PM

    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?

  • by zellyn on 5/11/22, 4:58 PM

    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.

  • by majkinetor on 5/11/22, 6:25 PM

    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

  • by epaulson on 5/11/22, 8:32 PM

    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.

  • by d4rkp4ttern on 5/13/22, 11:06 AM

    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.

  • by ABraidotti on 5/11/22, 4:57 PM

    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?

  • by andrerpena on 5/11/22, 8:32 PM

    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 :(

  • by alphang on 5/11/22, 7:32 PM

    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.

  • by seanwilson on 5/11/22, 6:58 PM

    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.

  • by fellowniusmonk on 5/11/22, 6:09 PM

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

  • by schemescape on 5/11/22, 8:16 PM

    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.

  • by IshKebab on 5/11/22, 5:17 PM

    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.

  • by mikelabatt on 5/12/22, 4:01 AM

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

  • by gambler on 5/11/22, 7:15 PM

  • by cercatrova on 5/11/22, 7:37 PM

    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.

  • by meshaneian on 5/11/22, 10:49 PM

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

  • by lordleft on 5/11/22, 7:50 PM

    This is an almost breathtaking documentation site.

  • by creakingstairs on 5/12/22, 1:44 AM

    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.

  • by annagrigoryan2 on 5/12/22, 5:26 PM

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

    I guess it's my lucky day.

  • by nik736 on 5/11/22, 3:24 PM

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

  • by AtNightWeCode on 5/11/22, 6:09 PM

    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.

  • by inson on 5/11/22, 10:31 PM

    Is this a new type of Jinja?

  • by data_ders on 5/11/22, 3:59 PM

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

  • by fedeb95 on 5/11/22, 7:49 PM

    the pointer is annoying though

  • by dragonwriter on 5/11/22, 3:59 PM

  • by dallasgutauckis on 5/11/22, 3:28 PM

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