Previously, for a long time typedoc was used to create method summary (API), this is a standard way to lay out TypeScript declarations, is quick to customize and works out of the box.

It has been enhanced to suit our needs with plugins and extensions to built-in theme.

And if in case of cover page everything looks relatively good, declarations themselves don't look so comfortable anymore.

Things got even more complicated once we need to add libraries. We tried to do several things — convert all declarations separately to create multiple packages, use plugins for built-in monorepo support and more. Results were not worth it, a backup of this variant can be found in a separate repository. It was decided to start from scratch. Or almost.

Attempts to generate a built-in method summary were made as far back as 2022, when documentation had just started its development. More steps were taken to build declarations correctly, because documentation could only be generated from ES6 modules with exports. Our declarations requires visibility in global context and don't support such a thing. We had to struggle with this.

It was hard enough to find screenshots, but you can see the comit of migrating to a new structure here.

Result, honestly speaking, even now looks quite controversial. And nothing was decreased from build time on older Docusaurus, we had to change amount of allocated memory. Building a site took about (!) an hour of real time instead of a couple of minutes. Saying that results are not worth it is not to say anything.

Overloaded sidebar slowed down loading unthinkably. We required to implement our own converter, added our own components for our needs. Everything was implemented for work, but it was frankly inconvenient to use it. So we decided to use pure typedoc.

Yes. But don't be so quick to judge, just look at results.

Changed everything that could, from approach to complete stack on what everything is built on. It is based on an abandoned library, which you can find here. There are plans to publish a fork for further development and use in other projects, but after migration to a new method stack is complete.

Pages are transformed by Docusaurus itself (engine on which a whole documentation is built), they consist of an index, a summary on right side for quick navigation and declaration itself. Method descriptions are flavored with new components and tags, all in the manner of 2022, but much more diverse.

Signatures are contained within a single method and navigating between them is easier than ever, you can click on a desired type at once to navigate to it (previously methods were separated):

Declaration description depends on chosen signature, description itself can be complicated and long, but even so, reading it should not be a problem, just go through summary and select needed:

You can see new cards in that description, they are created from @remarks, @example, @deprecated and @throws tags in your declarations, they are complete blocks for long and less-than-long descriptions:

My declarations? Yes, now, in addition to Core Engine declarations, this site also contains mods and libraries. Absolutely everyone can add them by pull-requesting for this folder:

If for some reason you want a complete list of available declarations, you can get it from a repository, or on website itself in a special page.

Of course, inconveniences can be found already during use, they are mostly related to sidebar, which even though it works fast, not as before, but still not most convenient. This is solvable, attempts are already being made to improve it. Eventually it is planned that navigation will become nested and will have a similar visual part as page indexes.

And while development continues, you can test a new approach of API generating at a public address. Previous version will be available for some time, but only when opened via external links (inside documentation we are testing following references to method summaries). What do you think, did it become more convenient?