markdoc VS vrite

Or please share any API documentation tools you use that is opensource and NOT Swagger.

Stripe has Markdoc[0] but it doesn't seem to be automated in any way.

[0]https://markdoc.dev/

Try using https://markdoc.dev/ .. this is the documentation tool/editor by Stripe and it also powers the extensive documentation of the Stripe product itself .

Extension frameworks like Stripe’s, MarkDoc allows documentation to have code examples in multiple languages.

I'm bullish on Rust, but there's a long way still to go. The overhead of passing values across the boundary between JavaScript and Rust is quite high. There are a lot of cases where you want to be able to provide a dynamic configuration to Rust, ideally in JavaScript, and that's still pretty costly from a performance perspective.

One of my projects (https://markdoc.dev/) is a Markdown dialect that supports custom tags and a React renderer. I recently experimented with implementing a parser for it in Rust in order to increase performance. My Rust-based parser is significantly faster than my existing JavaScript parser, but then I have to serialize the AST in order to move it from Rust to JavaScript. I'd like to implement the entire processor in Rust, but I need to let users define custom tags in JavaScript, and the overhead of going back and forth is far from ideal.

I'm hopeful that the recently-ratified Wasm GC proposal—which introduces managed structs and arrays that don't cost anything to pass between the Wasm environment and JavaScript—will help a lot. But it's going to take awhile for Wasm GC features to land in LLVM and be properly supported in Rust.

Consider going down the docs-as-code route. There are open source options that require an investment of time for you to become familiar with the tech stack, so learn Markdown and Git if you haven't already. Stripe (who many consider to have some of the best documentation available) created Markdoc as a means of easily maintaining solid docs with some of the fancy quirks of the upper-end doc tools, including content re-use.

Most modern developer blogs and documentation websites have one thing in common— they run on JAMstack (static websites) and their content is file-based and powered by Git. This allows multiple developers to collaboratively edit content with perks like versioning and version control. In this tutorial, we’re going to see how we can build a simple yet powerful and interactive blog with Next.js and Markdoc.

Hola. Former Stripe employee here - they use Markdoc: https://markdoc.dev/

These reasons (and many others) are why I decided to create Vrite - an open-source developer content platform.

Vrite is an open-source developer content platform, featuring extensible editing experience, content management tools, and powerful APIs. It’s intended as an all-in-one, collaborative solution for product documentation, technical blogs, and knowledge bases.

So, I've been building Vrite as an open-source project for a while now, and I'm happy to finally share it here - with v0.2.0 now having official self-hosting support.

Let’s start by getting into Vrite. You can use the hosted version (free while Vrite is in Beta) or self-host Vrite from the source code (with better self-hosting support coming soon)

You can use Vrite via the hosted version (that’s free while in Beta) or self-host it from the open-source repo (though good support for self-hosting is still in the works).

Since Vrite (and Vrite Editor for that matter) is currently in Public Beta, new features and improvements are in active development. The best way to try it out right now is through the hosted version at app.vrite.io (free while in Beta) with better self-hosting support in the works.

The editor itself is a standalone app, extracted from the larger Vrite CMS project (https://github.com/vriteio/vrite) which you can also test out (only with sign-in) here: https://app.vrite.io/

The main output is JSON ProseMirror format. Other formats are processed from this JSON using Transformers and Vrite SDK: https://github.com/vriteio/vrite/tree/main/packages/sdk/java...

In the GFM transformer I try to follow GitHub Flavored Markdown spec, which technically doesn't support embeds. Since I didn't find any "common" syntax to use for the embeds, I just left them out. They're still there in JSON and HTML outputs.

That's one of the drawbacks of MD. That said, I plan to add an option like Markdoc, which has clearly defined spec for implementing custom blocks like embeds.

That said, for now, if you sign up for the full Vrite CMS, you can create a custom Transformer and process the output so that embeds are included in your desired format. That's what I'm doing for auto-publishing extensions for platforms like Dev.to and Hashnode. I don't know what your use-case is, but I thought it's worth noting.

The process basically came down to figuring out the position and size of the block node, given a selection of an entire top-level node or just its child node (source code):