I’m aware that Lua is still experimental, so maybe this is just because I’m jumping the gun on this, but… Something I’m finding a little bit frustrating is when the documentation doesn’t line up with my current installation. To explain what I mean, here’s a quick example I just ran into:
I’m experimenting with Lua and trying to render an html block as output, but I’m getting an error message about trying to index nil.
So I go to the documentation page and search up “html”, because I remember the syntax being something like:
return {
html = "<div>Some Html here</div>"
}
That brings me to the current documentation for Space Lua Widgets which seems to suggest that I need to wrap the return in a widget.new() call. But that’s only true in the edge build from what I can see on the changelog page.
It would be helpful if there were an archived version of the pages tied to each release version. So instead of silverbullet.md/Space%20Lua, I could go to silverbullet.md/0.10.4/Space%20Lua and get only the documentation that’s relevant to the version I’m using.
Sadly, doing what you propose is not so simple because silverbullet.md itself is hosted on SilverBullet, and unless I create full copies of all docs (and rewrite all page references inside), exposing versioned docs under e.g. 0.10.4/Something would be quite a bit of hacking (committing a full copy of the website docs for each version, rewriting all references). Alternatively I could release branches to sub-domains, but then I’d end up hosting dozens of SB instances
A more pragmatic approach may be to only deploy new versions of the website when a release happens, since probably 90% of users (wild guess) are using a release version. So at least then it would be consistent with what they have (and likely forward compatible with edge).
Plus you can always checkout to the tag you want on github and browse through the docs there. It’s not as ergonomic, but it works. Or even clone the repo, checkout and start the sb server locally.
I think that would actually be great. I feel like I’m usually going to be on the most recent stable release so that would be sufficient. I’d think the main documentation should reflect the most recent stable and then there could be a separate instance for edge? Or even just having both versions in the docs with labels indicating which is which. Rather than replacing a section, duplicate it, label each and then make the updates? Then when a new version is released you could just go through and remove the old version sections and the “edge” labels.
