I recently installed v2 via docker image into my docker compose stack with Caddy and oauth2-proxy to keep things secure. That works great (although I couldn’t get SB to listen under a path but that’s another topic).
Since then I’ve become a bit frustrated trying to find help on writing space lua and understanding the capabilities and features of silver bullet. I never used v1 and have no idea about it so maybe the community has a lot of knowledge from that.
Are there any sites dedicated to v2? I’m a former Obsidian user and there was more than enough info on every aspect of that - perhaps I was spoilt for choice there.
Can anyone suggest anything please? ChatGPT isn’t much help as it just keeps using v1 as it’s reference.
https://silverbullet.md/ Is basically all there is right now for v2. Silverbullet is currently still under heavy development (thanks to zef) and a lot of things are changing and getting updated. Most of the stuff is “stable”, but spacelua is still very young and there hasn’t even been a proper release for v2. So it’s basically just a matter of time till the docs can get more in depth and this forum fills with resources. If you have specific questions you can always ask them here and help fill up this forum . The docs should give you a decent starting point on what it is and what you can basically do.
The general application functionality should be more or less covered in the Manual. All the Lua stuff perhaps less so, but what would be great is some input on the documentation you’d expect or look for. As the developer it’s sometimes hard to guess what is not obvious
include manual + API in SilverBullet app (like /Library/Std)
manage docs (and stdlib?) as a public git repo for community collaboration
Hi @zef! What are your thoughts on bundling the manual and API documentation into every installation of SilverBullet, the way the stdlib is? (In other words, on a local deployment, users should be able to access the manual at http://localhost:5000/Manual and API docs at http://localhost:5000/API.) and then maybe putting a link to all three (manual, API docs, stdlib) in a “Learn More” section of index.md?
I would imagine that the SilverBullet community consists almost entirely of power users, which makes discoverability of the docs really important. Personally, I’d like to be able to access the manual without leaving SilverBullet in the first place (i.e., via the page switcher). What’s more, I’m sure the docs required a nontrivial amount of effort, and I think that placing them front and center is the best way to maximize your return on that effort.
It might even be prudent to place all these things in a dedicated namespace so that it didn’t conflict with the files in a user’s own space. Maybe something like /Docs, /Help, or /Built-in?
As someone who’s written a lot of technical documentation, I would love a way to contribute to the docs directly. I know SilverBullet isn’t built for collaborative editing or submitting suggestions for review by the document owner, but I think there’s a lot of friction to the process of reaching out to you with feedback and waiting for you to make the time to update them. What are your thoughts on creating a public git repo of the docs, so that users can submit revisions as pull requests?
Then, the SilverBullet client could even periodically pull updates of the docs from GitHub (or wherever) and cache them to serve to the user when offline.
The docs and the stdlib are in the repo, you are free to contribute.
You could import the docs by writing an importer. The whole keeping 3rd party stuff in your space has been discussed a lot and there still isn’t really a perfect solution.
The whole keeping 3rd party stuff in your space has been discussed a lot and there still isn’t really a perfect solution.
If it can be done for /Library/Std, then what is the argument against doing it for docs? It’s no accident that the docs are written in markdown and served from SilverBullet itself; they clearly serve a double purpose as a demo of how to set up a space effectively.
What would be better for new user onboarding: to have that accessble from inside a fresh install, or to make them jump back and forth between two visually identical instances of SB to learn stuff and then try it out?
How’s this for a solution? If namespace collisions are a concern, the docs could be opt-out instead of opt-in—something like
-- CONFIG.md
```space-lua
config.set {
docs = {
hide = true, -- Opt out of built-in docs entirely
root = "/Docs", -- Set custom path for docs
},
}
```
Then, the first page of the manual could include an admonition that explains this option.
The docs and the stdlib are in the repo, you are free to contribute.
Ah, of course. The suggestion was really about proactively inviting open collaboration, like a wiki would. It’s not the same, of course, but I think it would provide a stronger signal that outside contributions (and even makeovers) are welcome—assuming that is something Zef would want.
This seems sensible to me. I must say that the actual need to visit silverbullet.md website every time I want to read documentation (and wait until it synces) is indeed quite annoying… And what if I am offline at the moment?
Agree built in docs would be useful. For my actual use case though I find examples are generally enough to get me started.. for example - creating a previous/next link for daily notes, a link to create a new daily note.. getting and modifying data from queries.. how to write more advanced queries.
Further than that I guess, API calls/integrating with other stuff? But yeah, space lua docs very much appreciated even if it’s just a handful of examples. Thanks
The website is 15MiB1.3MiB of data, the current full silverbullet bundle is 4.4MiB. Bundling it just like the Library would be pretty heavy (+340%+29% in bundle size). And SB is targeted towards power users I think a lot of people know SB and wouldn’t need that, but would still have to live with the bundle increase (even when disabled, which would probably have to be done over an env variable, because client/server side, similar to the index page).
What I see as an option is having a button on the landing page which gives you the option to import the docs. This import could live in the stdlib and would only be a minor increase.
To add to this point, in addition to usage examples, I would really appreciate a link the API docs to each method’s implementation in space lua. Some languages (notably Rust, Go, and Ruby) do this, and it’s a very valuable learning tool.
Where did you get this number? I just checked on latest master and am seeing 1.3MiB. That number goes down to 448K if you include only markdown files:
$ git clone https://github.com/silverbulletmd/silverbullet
$ du -sh silverbullet/website
1.3M
$ fd . silverbullet/website -e md -X du -hc | tail -n1
448K total
Does this change your position? or am I missing something?
(As for myself, I would argue for making the docs opt-out on principle, regardless of the size. If they were really 15+MiB, that would call for a rewrite/reorg, not an exclusion from the application itself.)
This makes no sense. Are you trying to tell me that all the emacs and vim power users out there think that the built-in docs for those editors are just a waste of disk space?
Whoops, my bad had a database from v1 days in there, hidden by the gitignore. +29%/+10% seems much more manageable imo.
I haven’t seen anyone experienced using the vim docs on a day to the basis. Yes it can be very useful, but there is still non-neglectable group of people, which probably don’t need it (+ Because SB is used in the browser the hurdle to open the docs website is lower). In the end it’s a cost-benefit thing, which for +10% probably isn’t bad.
But this still poses some issues:
“Exclude docs” via env variable (Kind of have to if you include them the same way the library folder is included)?
If you only include the markdown, how do you ensure that there are no broken links?
(I always dreamed of a separate reference and docs (This would solve point 2). With docs focused on examples and ideas, maybe even sharing stuff like a extensive task implementation, etc. (Could even be a wiki like you mentioned). And the reference would be focused on documenting behavior like the markdown syntax and the spacelua api, etc.
The problem with that is that it adds a massive amount of complexity to maintaining the project. A folder in the repo + a github action to host the app itself as the docs is just very beautiful and simple to maintain.)
. The docs should give you a decent starting point on what it is and what you can basically do.