I saw several people saying that developer docs are great, however, other than the example plugin and related guides, the API reference is quite sparse in explanations. To give you an example, the app.vault.modify method doesn’t say a thing about what it does. Yes, it takes a file, a string data, and a third optional argument, but, for what? What does it do?
In that sense, the github API definition is much more complete, so I don’t understand what is the role of the official API reference:
The documentation website definitely needs improvement. I’m working on developing my first plugin and found that the website didn’t have a whole lot of seemingly necessary info. I’ve just assumed that the people developing advanced plugins for Obsidian were wizards or something. As an example, I submitted a Pull Request the other day because the docs didn’t mention that the icons from Lucide they support only go up to a certain version number and I had to discover that myself. I can’t imagine the difficulty for something less obvious. It’s rather hard to improve the docs and suggest changes when I’ve no idea what’s missing or what is actually being described.
I know the devs are hard at work at many things, and I’m not here to criticize them for a lack of documentation when I’ve hardly made anything more advanced than simple websites. I really like the program and want to develop plugins but am finding it a tad difficult to do so when I’m lacking information.
That being said, perhaps the answers are in the Github. I’ll take a look at that.
I think the part you’re missing is the first quote; I’m not sure that’s the general vibe that I’ve seen.
No disrespect at all to the devs, but I have 6 plugins out now, and I spend most of my time developing them hunting around in console mode or just trying different combinations of parameters out until I find what works. Sometimes you’re lucky and you find another plugin repo with code you can use.
If there are good docs out there, please can someone direct me to them too
I may have misread someone praising some plugin docs and I though accidentally they were referring to obsidian docs itself.
At least I’m happy to see that I’m not stupid or missing something. The bad part is that I’ve already suffered exactly what you described in the past and Im not really excited to experience it again.
Yes, I saw it, but that doesn’t change anything. Github type defunitions are still the only source of information and the official API reference docs are useless
There was a post recently praising the developer docs. But at think the person was new to development and had made a relatively simple plugin, so maybe they didn’t experience the docs in their entirety.
Also the docs do have a Github where people can file issues and pull requests. Obviously they should just be better, but if you figure out stuff that’s missing you can help save others from the same problems. I don’t develop plugins (yet?) but I’ve been sporadically filing issues on the user docs.
EDIT: Apparently The API reference is auto generated and can’t be contributed to.
Have you visited the two links that I have provided? Where is the information contsined i the JSDocs in the compiled reference? Thise are what are actually providing value, and they’re missing
The link is at the bottom of the docs home page, in the Contributing section:
If you see any errors or room for improvement on this site, feel free to open an issue or pull request on our GitHub repository. Thank you in advance for contributing!
Wellllll… it turns out you can’t actually do that…
I submitted a plugin where the devs requested I use checkCallback. Searching the docs for checkCallback returns this page: checkCallback - Developer Documentation
I couldn’t understand the function from that short piece of documentation, so I searched Github for other plugins who had already implemented it, and found working code that way.
I then submitted a PR with an example usage I created to help save others from the same problems.
And it gets rejected/closed with the message: “These reference files are automatically generated, when we run the generation again next time the example will be overwritten.”
So, sadly the next person won’t see an example either.
This is the first time I’ve been disillusioned with Obsidian. It took effort to figure out how the function worked, write that example, and submit a PR. And that effort was entirely pointless, and the docs are no better than they were before I spent all that time.
I understand closing issues and bug reports that don’t follow templates, but to just send a contribution to the trash? … You can believe I’ll never bother trying to improve those docs ever again.
Please forgive the lack of purple in my name on the forums (yet), but this is Sigrunixia from Discord/Rebbecca from Obsidian Support.
I’ve started the process this past week in getting the contributing guidelines for the development documents updated, because of this reason, among others. I encourage you to continue raising issues, as @CawlinTeffid has, because it does help us find these blind spots. Because of the PR, which in the future will be make an issue first, then create a PR, we are looking at what can be done to update the docs as a whole to make them more user-friendly.
The messaging could have been better (It always can), but it is nevertheless the action we would have to take in this instance because our auto generator needs updating as a whole to address this for every option. I don’t know when we will get that update out, but it is in active discussion on how to approach it so we can delegate bandwidth for it.
So if you find any little thing, please continue to make an issue.
Which requires editing how the autogeneration adds examples in file, and how it applies aliases to files, to improve search results. Publish search results only pull from aliases, file names, and file headers, which is not the most helpful when a page alias name is obsidian.Command.checkCallback.md.
An update to make that Publish search more expansive will be happening down the line per our Roadmap.
I also see an update was added to the original PR, so I’ll leave it to the dev members of the team to see what comes of their fixes.
Edit: And I’ll update when we have something more concrete.
To let everyone know, I have merged in a PR to update the contributing documentation (It hasn’t been deployed in the Publish site yet), that reflects how changes should be requested.
The main readme of the page now also indicates what folder/files are autogenerated.
We’re still working on the updates to the autogenerated files.
Publish search results only pull from aliases, file names, and file headers, which is not the most helpful when a page alias name is