Thank you Docusaurus

The success of any software depends partly on its documentation. A good documentation can make or break a great software because people need to know how to use it and in case of a developer facing software, it needs examples and properly documented API. SQL Frames uses TypeScript and a nice API documentation can be generated using the TYPE DOC system. However, to show case all the features and provide a low-code software documentation experience, it needed a good documentation framework. In addition, as SQL Frames runs within the browser, a key requirement is to be able to author documentation with inline live examples.

There are many static website generators out there some of them focused on documentation. I have been familiar with the Hugo static site generator that is known for its speed and speed translates to productivity (the very reason why SQL Frames has been conceived to run within the browser). But after researching the Hugo templates for documentation, I wasn't sure if some of my requirements such as embedded live examples with state across pages could easily be achieved. Similarly, there is no winning doc theme either. So, I was looking for alternatives and that's how discovered Docusaurus at the jamstack website.

Docusaurus is from Facebook, the guys who provided the great React library. Upon reading more about Docusaurus, a couple of things attracted me to it.

1. The ability to author documents using markdown.
2. The ability to mix React components with rest of the documentation.

Since I wanted to have live examples within the documentation, Docusaurus seemed like the perfect option. And it turned out to be true. But to get there I had to take care of a few things first.

Thing is, SQL Frames UI is developed using PREACT and not React. But one of the goals of SQL Frames is to make the UI to be easily integrated into any of the popular frontend technologies including React. So, this felt like the right opportunity to showcase how the UI can be made available within React. So, after wrapping up a simple wrapper and creating a React component, everything almost came together. Except it didn't.

SQL Frames has a dependency on Monaco Editor. As a result, it is not possible to do server-side rendering. To solve this problem, the react component had to be made to load dynamically and together with code splitting, it gets resolved on the client. Since the examples are expected to be live demos anyway, this is not a problem. I may have to revisit on how to do server-side rendering with SQL Frames if there are any other strong use cases.