Docs that live with your code.
Keep your documentation as markdown in the same git repository as the code it describes. Write it in SilverBullet, review it in pull requests, and ship it with every release. Publish it to the world if you like, or keep it in the repo.
Documentation usually lives somewhere else: a wiki or a docs platform, away from the code. It falls behind with every release, nobody reviews it with the change that made it wrong, and there’s no telling which version of the docs goes with which version of the product.
Let’s talk about SilverBullet’s documentation
SilverBullet’s own documentation lives in the docs folder of the SilverBullet repository, right next to the code it describes. It’s written in SilverBullet, its changes go through the same pull requests as the code, and the same folder is published as docs.silverbullet.md. Its navigation, its section pages and its API reference are built with the same features you have.
It’s just one example of how a space could be set up. Yours will likely look nothing like it, and that’s exactly the point: you make SilverBullet work the way you want.
A documentation site, built in SilverBullet.
The start page of SilverBullet’s own documentation: the same space the team edits, open to the public for reading.
Built with: Space Lua · Publishing
See the code: Library/Website.
Section pages that list themselves.
Each section page lists its pages with a one-line summary, generated from the space. Add a page to a section, and it appears.
Built with: Queries · Space Lua
See the code: Library/Website.
Navigation, built for this site.
The tree on the left isn’t the standard page tree: it’s a custom view, defined in a few dozen lines of Space Lua. A hand-curated list puts every page in its section with its own icon, and the tree follows along as you move between pages. CONFIG docks it on the left by default.
See the code: Library/Website.
Notices from tags.
Tag a page as experimental, and an event hook adds a notice above it, on every page that carries the tag.
Built with: Tags · Events · Widgets
See the code: Library/Website.
And also...
Versioned with your code.
Open your repository’s docs folder as a space with SilverBullet Desktop. Every edit is a plain markdown change: it shows up in the diff, gets reviewed in the pull request next to the code it documents, and is tagged with the release it belongs to.
Publish it, if you want to.
On SilverBullet Server, give the public read access to a space with one setting in the dashboard. Visitors get the full SilverBullet experience, with links, Linked Mentions and live queries, without an account, while you and your team keep editing the same space. Add full-text search with a library, as the documentation site does.
Styled your way.
A published space is styled like any other: a bit of CSS in a page, from colours and fonts to a whole theme, plus icons and prefixes on pages.
Or pick from a huge ecosystem.
Markdown is everywhere, and so are tools to publish it. If SilverBullet’s own publishing doesn’t suit you, use any other: a space is a folder of standard markdown, so static site generators such as Quartz, MkDocs or Hugo can publish it straight from git. Live queries and widgets can be baked into plain markdown first, so whichever tool you pick sees the result.
Your docs, next to your code.
Write in SilverBullet, review in pull requests, and publish the same files if you like. No second copy.
Get started