Markdoc: Stripe's Markdown-based authoring framework | Hacker News Reader

Markdoc: Stripe's Markdown-based authoring framework

markdoc.io

810 pointscolinclerk146 comments

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.

Would be very cool with some information on how they work with creating the docs, manage them etc.

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.

I think they meant "better than my docs are now with $0 funding" rather than "better than the median company with $2bn funding"

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

It helps when you have people staffed full time for the work. Stripe views docs as a product, not an afterthought

Totally agree. There are other companies, though, that have people staffed for the work and they do not do nearly as good of a job. I shall refrain from naming names. :)

They also treat docs as a way to add detail to and flesh out well-designed products rather than as a way to disclaim and explain things they didn’t feel like or have the resources to fix.

> I'd love to know if Stripe has any secrets to keeping their Docs updated.

Simple: documentation is part of the "definition of done". This goes for API docs (e.g., editing field descriptions) and integration guides/high-level docs. The feature/project isn't done if no one knows how to use it.

I would describe stripe docs as 'acceptable'. Don't get me wrong, I personally have brought them tons of business and work with their API more than a human should. My only issue is that if you are working with their API, you will discover HUGE gaps if you step outside "the norms". That being said, they are a step above everyone else, which should tell you something. Also, the comment regarding open-source applies 300%.

It seems that many Stripe team members walk the HN halls, if you were to give a few examples of the "HUGE gaps" you mentioned they might fill them in.

Yes—would like to hear more about how we can fill in the gaps. (Can also email me directly at edwin@stripe.com.)

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

Unfortunately my experience has been different; I found that Stripe's Go doc doesn't match their API and while searching on it I found that someone else had mentioned that to their personnel over freenode 2 years ago.

So I raised an issue on GitHub[1] on Apr 9 and hasn't been attended to yet.

On a more serious note, Stripe's payment links doc seemed to imply that tax rates are automatically calculated if the tax rates are set(as we do with code when we pass the tax_id), But I found after couple of payments that tax aren't being charged, On conversing on Twitter with the payment links dev I came to realize that the required option was not there for me[2] and then after couple of hours with their support staff I was informed that the options was not available for India as 'Stripe Tax' is a separate product.

Overall, I'm happy with Stripe's tech; at least compared to the other options I have. But their docs have caused me some frustrations.

[1] https://github.com/stripe/stripe-go/issues/1447

[2] https://twitter.com/joshuaackerman/status/144759582096702259...

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

Thanks for posting this. What is a good way for learning about the salary and compensation for this position? Nothing specific, b it just ballpark to determine if there’s basic compatibility before applying.

The title is too specific to get good numbers from googling and I worry that docs product managers wouldn’t make what typical product managers make. [0]

[0] https://www.glassdoor.com/Salary/Stripe-Product-Manager-Sala...

It's a normal PM position and you'd be in the normal PM salary bands. You'd be my peer. I manage the server-side SDKs, the CLI, the VS Code extension, the React Native SDK, the API upgrade experience, etc. We'd be in the same ladder. (AFAIK there's just one PM ladder at Stripe)

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 and flexibility, but at the cost of complexity–content can quickly become as complex as regular code, which can lead to maintainability complications or a more difficult authoring environment.

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

> React is also a "fully declarative approach to composition and flow control".

MDX, which allows embedding JSX isn't fully declarative, since arbitrary imperative structures can be used in JS blocks in JSX.

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.

We handle this by having some components that don't require much training to use (<Note />, <Warning />, <Function />).

I don't think you have to choose between "can be powerful" and "can be simple."

If you want to lock things down so no one EVER puts code in your docs, Markdoc looks great.

> Okay, but has that actually happened in practice?

Before we built Markdoc, our documentation was powered by ERB (embedded Ruby templates). Having content mixed with arbitrary code made it incredibly hard to reason about either. Because Markdoc is a declarative language rather than imperative, there's no intermediate state to keep track of, making things easier to follow.

At Stripe, both engineers and tech writers contribute to documentation. Markdoc makes things easier for everyone by keeping the content separate from the code, while still making it possible to build more interactive experiences when you want to. (For example, our integration builder [0] is also powered by Markdoc.)

[0] https://stripe.com/docs/payments/quickstart

I am a huge fan of this style of page! is there an OSS example of this in full? I would be very keen to see what goes into making such a dynamic page in markdoc looks like

Not Markdoc, but there are several OSS examples of how you can do something similar with MDX + Code Hike. https://codehike.org/

Quick question. How do engineers and tech writers use the "live editor" functionality that seems to be in the open source repo? Do you edit in the live editor and is it set up to update the underlying repo? Or do you just modify the markdoc files in the repo with your own editor?

I like that they write it as a trade of. I think I still prefer the maintainability complications of "docs as code" https://www.youtube.com/watch?v=xEu3t-KJVVg

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

The quoted text says "as" and clearly intends that meaning.

Ah, thank you for the term in question. Found a relevant link: https://www.writethedocs.org/guide/docs-as-code/

"There is a lot more to building a proper Docs as Code workflow. There are a couple books we recommend that you check out:

    Docs Like Code - Anne Gentle
    Modern Technical Writing - Andrew Etter
"

That's not how language works, their phrase (that does not actually have a widely used established meaning) means what they meant, not what you say it means.

Yes, that term does have a widely established meaning within the specific context of discussion, technical writing. If the commentator is unaware of what 'docs as code' means in the context under discussion and meant something different, I encourage them to disambiguate by picking a term not already so defined.

I haven't heard of MDX before, but this looks fantastic. The API looks more intuitive than Markdoc. https://mdxjs.com/ for anyone else wanting to learn more.

mdx is great, especially if your team is already fluent with react/jsx. You might also be interested in docusaurus https://docusaurus.io/ as it has support for mdx built in.

If you want to play with MDX without having to set it up, check out https://motif.land. It comes with a collaborative editing environment too, that is incredibly easy to use for authoring markdown (our non-technical folks use it too).

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

After looking through Docusaurus, GitBook, and a few others, I also ended up with mkdocs and github pages. It’s very straightforward to setup.

I spent 6 months assessing the options came down to ‘Material for Mkdocs’.

Does Mkdocs have functionality to auto-generate docs from docstrings? I’ve been using Sphinx with RTD (ReadTheDocs) theme for python code. Wondering if Mkdocs can somehow be better.

Author of Material for MkDocs here. MkDocstrings [1] implements automatic generation of reference documentation from sources. It's language-agnostic, actively maintained and currently supports Python [2] and Crystal [3]. It also integrates nicely with Material for MkDocs.

[1]: https://mkdocstrings.github.io/

[2]: https://github.com/mkdocstrings/python

[3]: https://github.com/mkdocstrings/crystal

This is great, thank you.

Another important requirement for me is support for Math notation in docstrings and elsewhere. Looks like MkDocs supports mathjax?

https://squidfunk.github.io/mkdocs-material/reference/mathja...

Jup, MathJax is supported with minimal setup: https://squidfunk.github.io/mkdocs-material/reference/mathja...

Thanks. The MkDocs docs looks great. Would you be able to point to a sample (python) repo that has various configs etc that I can tweak? When starting with Sphinx + ReadTheDocs this was the most time consuming part , it took me several hours hunting down various docs and examples.

I recommend checking the list of OpenSource projects that use Material for MkDocs [1], for example FastAPI [2]. Alternatively, you can clone the Material for MkDocs repository, as the docs are built with itself.

[1] https://github.com/squidfunk/mkdocs-material#trusted-by-

[2] https://github.com/tiangolo/fastapi

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?

Upon further inspection, I think the biggest difference is that Markdoc uses Nextjs which means you can write React right in the middle of your code and import React components. But then again, you have Gatsby that's also based on React and is built for static site generation, and supports Markdown.

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.

way cool! I work at dbt Labs and see a similarity with dbt jinja, where all dbt does is render the jinja tags into "pure" SQL. is this the same thing in that markdoc "compiles" markdoc files into markdown, that then can be used in static-site generators?

It’s not. dbt goes out of its way to avoid having to parse SQL into an ast; Markdoc is Stripe going out of its way to parse input to an ast. dbt’s approach is more similar to the ERB system Stripe mentions Markdoc replacing.

What are the advantages of integrating templating and markdown like that? If I'm using markdown with nunjucks, for instance, what do I stand to gain from switching to Markdoc?

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.

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!

I was in the same boat, wanting to migrate away from Jekyll+Liquid. Very glad they released this.

Any reason why this would be better than liquid?

Genuinely curious because we’re about to adopt liquid.

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

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?

Hey, if you really want to customize markdown with your own elements and their rendering/templating, check out SGML [1]. It's made for exactly this type of flexible and extensible document apps/sites, even allows custom Wiki syntax rules.

[1]: http://sgmljs.net

A bit of a tangential question.

What kind of project or business that you run that you need it?

How much hours do you estimate it would have taken you?

For my startup, which is built around Markdown notecards[1], we've been using markdown-it, which it seems is also being leveraged by the Markdoc project. So far I've written a couple of extensions for markdown-it and haven't really had any issues.

[1] https://supernotes.app

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?

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 ?

It's all custom; the frontend is React and the backend is Ruby. Our plan is to introduce Markdoc as an intermediary step to improve the authoring experience.

Just to add to that, "normal" markdown (I forget which flavor exactly) is currently used for the text blocks within the Stripe API reference documentation.

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

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)

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

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

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

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/

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

While completely true, and I personally prefer markdown documentation (or even just a README.md if I can get away with it), larger projects definitely benefit from rst. You're probably going to end up re-inventing parts of it, like all of these markdown documentation projects do via extensions to the language, or littering your markdown with HTML like <div class="alert alert-info">Note, this feature is only available on processors with SSE2 or greater!</div>.

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.

If you have to extend Markdown, the battle is lost. The basic core idea, is OK, but as soon as you find yourself needing to do more documenty things (lists with formatting, tables, etc.) its the wild, wild west - different extension standards CommonMark, Github style, etc., editor, or library of choice.

Not to mention all the special-custom-component standards now which require code... the whole point of Markdown was you could just use any old text editor and be just as well off as looking at a prettified version.

You have the higher complexity and learning curve anyways, more, even.

I guess, the bad design decisions in RST are bad, but there are equally bad design decisions in all these new extensions, editors.

Instead of trying use a hammer put in screws, we should just change tooling. If you need document-level formatting etc., plain-text formatting is cool but don't try to be markdown. Use markdown when you just need simple text docs, if you find yourself doing complex stuff maybe you shouldn't be using markdown, or at least not calling yourself "markdown".

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

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 implementation is the Python one. Frankly Python sucks. The Docutils code has no type annotations so good luck reading it, which you will have to do because...

3. The actual Docutils API is very badly documented. This is easily the biggest flaw. I have implemented a couple of custom directives for my company's docs and it was extremely frustrating to get it working. Pretty much down to using grep.app to search for examples of other random people that have figured it out.

So I would strongly recommend not using RST. I've been wondering what would be better for a while - normal Markdown is just not rich enough for good docs. This looks pretty nice though.

Latex output is nice, but not really super important in 2022 and definitely not worth the flaws of RestructuredText.

Do not use RestructuredText.

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

Funny you say that. I spent most of last week porting some of my rst based book authoring tooling to md/pandoc.

At this point using rst is like advocating for Subversion instead of Git(hub). (Which is actually a good metaphor considering where docutils is hosted...)

I say this as a (former) committer to docutils.

The LaTeX support is ok in rst if you want to create something similar to a Word document. If you actually wanted to print a book, you need to use something like my tool, rst2nitrile.

The Python documentation folks seem to be interested in abstracting Sphinx to markdown as well with MyST...

rst is a dead end at this point.

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

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?

Emacs org-mode with babel for executing code blocks to generate the diagrams prior to exporting to html/pdf is my flow for this. It still has a steeper learning curve for non-technical users, but if you use post-commit hooks you can have people just make changes that way and let the scripts do the work.

Obsidian.md is amazing; basically an OS for markdown.

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

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!

Have you checked out Quarto? https://quarto.org

"Quarto® is an open-source scientific and technical publishing system built on Pandoc

- Create dynamic content with Python, R, Julia, and Observable.

- Author documents as plain text markdown or Jupyter notebooks.

- Publish high-quality articles, reports, presentations, websites, blogs, and books in HTML, PDF, MS Word, ePub, and more.

- Author with scientific markdown, including equations, citations, crossrefs, figure panels, callouts, advanced layout, and more."

Does that sound like it meets your needs?

A few folks recommended Quarto to me when I asked about current recommendations recently. My main goal is physical books and that doesn't seem to be a first class citizen anywhere. Looking through Quarto, I can't find reference to markdown syntax for index entries (which indicates that they don't support it.)

Also, I'm heavily biased, but based on my experience I will need to hack whatever tool and I'm not really interested in hacking JS/TS. (My whole reason for getting rid of my rst based tooling is to simplify and sticking in Python simplifies my life, coding in JS/TS not so much.)

I'm also very interested in physical books. Can you point me to anything that supports index entries well, regardless of the language they are written in?

I certainly agree about expecting to need to hack, whatever the tool.

As I mentioned elsewhere, I've published multiple books using rst2nitrile. For example, Effective Pandas was written with it...

Bookdown seems to support index entries:

https://bookdown.org/yihui/bookdown/latex-index.html

I wouldn't be surprised if Quarto supports the same syntax, since they are related. But it is possible it doesn't.

It might. I'm not interested in hacking R.

I'd be very interested in seeing your markdown (pandoc filter) based solution, if you can publish it.

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

I've created a VS Code extension that provides a live Pandoc preview with scroll sync and support for executing code: https://marketplace.visualstudio.com/items?itemName=gpoore.c.... Adding support for diagrams would just be a matter of creating a config file specifying the diagram executable and command-line options.

Last week I ported my static physical book building tooling from rst-based [0] to markdown (pandoc filter) based.

I've used my rst tooling to publish many books (like Effective Pandas) and am wanting to drop rst in an effort to simplify my life. My pandoc toolchain is not in github yet, but preliminary exploration validates that I can publish my next physical book with it (with things like front matter, indices, etc).

In the process I messed around with MyST and mistletoe. I dropped MyST because it was evident I would need to mess around with Sphinx again. Been there done that. Too much abstraction.

Mistletoe would have worked too (I need to create custom fences/markup for a few features) but I wanted to see if I could do it with Pandoc.

The Pandoc distinction between Blocks and Inlines is annoying as is the requirement to handle everything at once. With Pandoc, you only get notified at the start of an element, not the end which probably complicates it a bit more than Mistletoe would have.

(I still need to port my slide generation tooling and will probably use mistletoe for that. For epub generation I think I will stick with Pandoc.)

0 - https://github.com/mattharrison/rst2nitrile

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.

Good question. You are right in that it is implemented as a mapping from type → SVG in the Markdoc docs site. However, diagrams don't need to be implemented this way.

In fact, on stripe.com/docs we use Markdoc + https://reactflow.dev to render custom diagrams (with translated content and everything). There is a good example of this in action on https://stripe.com/docs/payments/checkout/how-checkout-works, if you are curious.

Interesting. Thanks for the reply. I'm trying to understand what it would be like to adopt Markdoc as our internal documentation system. I didn't like the "spooky action at a distance" of defining diagrams far away from the text, so I'm glad to hear it's not usual practice :-)

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

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.

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.

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)

Looks like you should able to add markdoc into Docusaurus with plugins etc.

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

This is possible! Check out https://markdoc.io/docs/nodes#customizing-markdoc-nodes

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.

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.

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

https://github.com/markdoc/docs/blob/main/components/SideByS...

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.

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.

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

https://technology.reclamation.institute/pages/cured-html

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.

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

This is an almost breathtaking documentation site.

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.

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

I guess it's my lucky day.

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

I'm an engineer on the Docs team at Stripe. Can you say more about where you're seeing the animation and what it looks like?

I'm seeing weird effects from the "Try it out" text that chases the cursor. Sometimes it jumbles and freezes, etc.

Here's a picture of one weird animation, looks like others are speaking to something else though.

It looks like the "Try it out" is chasing the mouse, but perhaps someone tried to get a bit too fancy with it. Any mouse movement that is slightly irregular (speed, circular motion, etc.) makes for really wonky animations.

https://imgur.com/a/X4cZYaM

I see this when browsing between pages (Firefox, Linux)

https://user-images.githubusercontent.com/128088/167891663-c...

Another small bug, the ::selection colour in CSS matches the yellow background on your homepage so if you select text there (in the 'Get started quickly' bit) you can't see what you've selected.

Yes, this is exactly what I meant.

I see it on Firefox, not on Chrome (am on Linux). Very obvious, hard to miss.

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.

Is this a new type of Jinja?

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

Looks like JSP to me. Or maybe ASP? Or ERB? Not sure which one came first, but many templating languages use those tokens.

Given Stripe's ruby predilection, my guess is ERB.

Installed via npm, my money's on javascript.

the pointer is annoying though

Name collision with:

https://github.com/haghish/markdoc

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

The joys of parsing user input live and trying to display it immediately :)

Fix is up—thanks for calling this out.

Reply on news.ycombinator.com