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
