mdx VS markdoc

Official MDX site

For anyone wondering, MDX is a mix of Markdown and JSX: https://mdxjs.com/.

Storybook simplifies working on those hard-to-reach spots in your codebase by providing an isolated workspace. It is a separate framework-agnostic app within your repository. You can do everything from developing components to documenting all different component states and showcasing them nicely using MDX with clickable demos and interactively changeable component arguments. You can also test your components within Storybook. Storybook's add-on API allows you to tailor it to your needs.

You might want to reconsider the name. MDX is already a well-known technology that combines markdown with JSX https://github.com/mdx-js/mdx/

MDX - write JSX in markdown documents!

I think this would be great as an evolution of MDX (https://mdxjs.com/). MDX is already pretty popular for documentation and it plays well with React but unfortunately there is no framework that adds interactivity to MDX which will enable use cases like data applications.

This is where MDX comes into play. It's essentially a hybrid of JSX / React and a well-specified dialect of Markdown. Essentially, this allows writing texts that are as simple as plain Markdown, as well as creating complex components as you might have done in full JSX.

MDX is great for this, you can intermix JS/TS, JSX, and Markdown

https://mdxjs.com/

You can write your components normally and pass them in to be available in MDX

MDX — Write React code within Markdown.

Semantify was made for content creators, marketers, and anyone looking to enhance their long-form written content. Currently only supporting MDX-based content, It automates the enrichment of MDX blog posts by adding AI-generated Q&A sections that summarize the content, and recommendations for semantically similar posts. This not only makes the content more accessible and engaging but also helps in establishing deeper connections between different posts, ultimately keeping the reader engaged for longer periods.

Markdoc is a Markdown-based content authoring framework developed by Stripe. It extends standard Markdown by adding custom tags, components, and validations, making it more powerful for structured content in web applications.

Markdoc (https://markdoc.dev/) really had me excited, but I'm not sure it aspires to be all that I hoped it would.

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.