Frontend

i am about to embark on the journey of writing my own OpenAPI Spec → MDX generator for custom documentation. anyone done this before? any helpful links?

𝚆𝙾𝚁𝙺𝙸𝙽𝙶 𝙾𝙽: @vision 👁️ ✦  ensdata.net ✦ pugson.net/rfe ✦ 𝙿𝚄𝙶.𝙴𝚃𝙷 ✦ 𝙿𝚁𝙴𝚅: @rainbow 🌈 

https://github.com/o-az
—
https://x.com/awkroot

Are you using any base docs framework like Astro Starlight or Vitepress or all from scratch?

I am doing this *right now*.

I have found https://tx.shadcn.com/ and it follows all of the principles I want, so I'm following it pretty closely.

I reckon looking at something like how the zod library does it might be helpful as it’s mostly finding a comprehensive way to convert from one ast to another then compiling

Mintlify but it's paid with a free trail
mintlify.com/blog/steps-to-autogenerate

i tried this and it's all kinds of broken and underwhelming

Have you seen https://github.com/scalar/scalar ?

aspiring shrimp farmer ~ eng @ bloom (yc s21)

yeah. doesn't support many things i need to do and the design is suboptimal. i've tried them all and most of these parsers are shitting the bed when you have references and anyOf 401s

Regular human, Developer Experience at dynamic.xyz

i know i’ve seen your docs 😏 

tried mintlify but there are so many issues with their parser, they keep breaking the docs every single week with some new change, can’t get through to support, no way to make custom react components to inject into MDX. 

their marketing is way better than the actual product.

FWIW We use Mintlify which is MDX based in general, but for the API ref we just plug in the files after a mini transformation and it does the rest: https://docs.dynamic.xyz/api-reference/overview

Purple 🟣 #134
Building ScoutGame & CharmVerse.io

Love to talk about new ideas, build and use AI daily

yeah, will do this with the help of GPT. need to write it so i can feed it a remote OpenAPI spec file on every build and have it generate appropriate MDX files. internal only

This is the kind of bite sized task an LLM would be amazing at (if you’re ok with a bit of manual editing of the final results and not building a generator that’s intended for use by third parties)

on a similar journey. Unpopular opinion I thought docusaurus would do the job - but it kinda sucks on many levels