For me I think using markdown is good, and what is the problem when converting? MDX does not support all the features of adoc so we will lose some styles?
Yurii Palamarchuk <[email protected]> 于2025年12月3日周三 23:42写道： > > Hi Team, > > I want to improve the docs page and I'm coming up with two options: > > 1) Integrate the docs engine into the new website, so it works as a whole > system. The docs look beautiful, are easy to use, have search, sections, > "Copy Page" buttons and much more, aligning with the landing page design. > However, for this we need to convert .adoc to .mdx (just extended > markdown), that's the only price. I tried to set up a pipeline that will > still use .adoc as the source of truth, converting all the .adoc files to > markdown at a build time, but it doesn't work well. There is no > engine/processor that can do it out of the box, writing something custom > will take weeks, so it's not worth it. Automated solutions barely exist, > and honestly, after trying them I can say they produce irrelevant results > most of the time. Here is the link to the new docs webpage, it's not final > though and doesn't have the features I mentioned below. > https://hbase-landing.vercel.app/docs > Please check it out and give your opinion. > > 2) Keep the current docs website, but modify the css. I tried to play with > it a bit, and it's possible to make it look similar to the new landing page > style, even adding dark mode is probably possible. However, it's still old > and I cannot update it significantly. I would prefer to go with the first > option, it's a major step forward. Ascii docs is a very powerful format, > but unfortunately, its integration isn't supported by modern technologies. > Converting .adoc to .mdx would take some time, but it's not a big deal > since the AI can assist with it. I already did it for many > files, although they have to be slightly adjusted and checked manually. > > There might be other advantages of going forward with the first option as > well: > - Learning curve for the markdown is 0, while it's not like that for ascii > docs. > - With the new docs engine we could add the "Copy content", "Open in AI", > "Edit this page on GitHub" buttons > - "Last Updated" in the bottom of each section > - Better Search at zero cost, pure client-side > - Versioning > - Feedback > > Regards, > Yurii
