While there is technically a set of api docs, there is nothing explaining the purpose and proper use of the apis or the mentality behind the api’s design. While I greatly appreciate that such a fabulous tool as Logseq is free and open source, except for the api docs and Plugins 101 its extensibility is for all intents and purposes undocumented. It whets the appetite but it’s basically the first 2 chapters of a 10 chapter book. Rather it requires one to infer the design (the other 8 chapters) by reverse engineering existing plugins and the sample plugins.
At the bare minimum, if the api has an intentionality to its design, it should be possible to explain the where and why and how. It should provide and explain at least one practical example for each provided function as well as demonstrate which functions work well together. The examples could even cite (or link to) an existing plugin which solidly demonstrates its use of certain apis.
Given the current docs the learning curve for onboarding plugin authors is unnecessarily cumbersome.
I’m not meaning to criticize, rather I love Logseq. It’s the best FOSS tool I’m aware of. I’m suggesting that improved plugin documentation would be a boon to the plugin marketplace and to the product itself.
I’m expressing a desire for a teaching element, human explanation to be added. There are several interfaces and a bunch of methods whose use are non-obvious despite the autogenerated output. Whenever someone says “read the code,” not that you have, it’s usually a sign the docs are lacking. A guide for using the full api, something a human being took the time to think through and teach, is a far cry different from what’s available.
Hence what I am saying is that any other developer who wants to build better documentation can submit a PR to the above blob and it will show on the site. I.e. there is no need to create a brand new site for the plugin documentation.
In short, I fully agree that the documentation can be improved and the way to do improve the documentation is to update the blob.
I have a modest understanding of the plugin api, enough to build a basic plugin. I noticed things about the api which felt lacking and that’s why I made somesuggestions. But they may be the ill-advised suggestions of one who does not understand the right way of doing things. Other developers may have their own, perhaps, subpar ways of doing things.
To me it doesn’t matter whether the developer’s manual is a new site, a separate guide, or grafted into the existing api site.
If by “PR” you mean pull request I’m not sure who these pull requesters will be if not the team or individual who designed the api. I think it falls to the mind of the designer(s) to provide the why behind their design choices. The developer’s manual (e.g. updates to the blob) should not be made by just “any other developer.”
The more I’ve worked with the api, the more I’ve felt its limitations, perhaps because the docs don’t illuminate the possibilities. I tried twice to create a plugin meeting 2 seemingly simple requirements:
It should style elements matching a selector — easy!
It should provide a visual indication (a flag) of whether blocks matching the criteria in 1 exist anywhere on the main section of the page — difficult!
The first attempt tries to discover what content is on the page using the DB, but there are limits as Journal pages, for example, lazily load content. Plus there are other sections like reference links. The plugin can’t consistently tell what blocks appear somewhere on the page.
The second attempt accesses the parent DOM but—I forgot about iframe isolation boundaries!—that presents cross-frame issues. When I was developing it locally everything worked fine. It wasn’t until I installed from the marketplace that the issue revealed its ugly head.
Both attempts at matching content have their shortcomings.
Maybe the someone else who takes a stab at these 2 requirements can decide how robust the plugin api is. It appears to be good for rendering new, independent UIs, but it feels too restrictive to coordinate with the main UI.