devportal VS next.js

Hello folks, I am running a tech writing team (along with product management). I am not expert in documentation platforms. Today we have a challenging custom-built documentation platform based on Sphinx and a bunch of cobbled together technologies aiven/devportal: Resources for users of the projects on the Aiven platform (github.com) . Our documentation is in .rst markup language due to the Python focus.

Humble brag that the last one in the list (Aiven 🦀) won 2022 DevPortal Awards in the category Best DevPortal Beyond REST Platforms. If I added a list of great docs websites but didn't include the OG, it would be a crime. Check out one of THE BEST documentation out there - Stripe Docs, built using Markdoc.

You can find a list of Aiven's cloud providers on [Developer.aiven.io], which is also the portal where we host the developer documentation. To quickly retrieve a list of currently-available cloud providers, my colleague Lorna Mitchell wrote a Python script that pulls our cloud listing from the Aiven API and generates documentation, which is really cool!

Using Markdoc with Next.js

Released in 2022, Markdoc is a relatively new Markdown-based authoring framework. The Markdoc project is open-source and it powers Stripe's documentation. Their website has a live edit button which makes the website a playground for you to give Markdoc a try. Documentations created with Markdoc will automatically render with your React app and using @markdoc/next.js for your Next.js app.

A couple of weeks ago, we open-sourced Markdoc, the authoring tool powering the Stripe docs. To accompany the launch, we published a blog post showing how to get started using Markdoc with Next.js, using the @markdoc/next.js plugin. In this blog post, I’ll show you how to create your own plugin, using the one I wrote for Parcel, as an example, so that you can use Markdoc with it.

Official Markdoc documentation Markdoc repository Markdoc Next.js plugin repository Markdoc playground Next.js boilerplate demo