Basically yes, MDX doesn’t support many of AsciiDoc’s built-in features out
of the box. But we won't lose any styles. The main issues are things like
attributes (:foo:, {attribute}), includes (include::file.adoc[]), callouts (
<1>), and similar constructs. These are custom to AsciiDoc and can’t be
automatically mapped to standard Markdown.With MDX we can replicate all of them, but only by implementing our own components and rendering them manually. Markdown itself doesn’t have Notice/Info/Warning blocks, but MDX lets us build them. There’s simply no universal converter that knows how to transform the AsciiDoc syntax into those MDX components. But we don't have to implement these components manually, since the fumadocs framework we're using already has everything we need built-in. I tried setting up an automated pipeline, but it requires heavy customization and still produces broken output. In practice, converting with AI and doing a quick manual pass is much faster. On Thu, Dec 4, 2025 at 1:47 AM 张铎(Duo Zhang) <[email protected]> wrote: > 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 >
