First run experience and onboarding

SilverBullet has a lot to offer, but the learning curve is steep. I'd like to explore ways of flattening that curve: to make SilverBullet more accessible to new users.

I've been using SilverBullet for 4 years so it's hard for me to imagine what the first run experience is and what is unclear and what would benefit a new user to more quickly get up to speed and understand what SB is and how to use it.

Do you have suggestions, or things you ran into early on?

I can imagine minor things like changing the new space template with something more instructive. In the past it contained a mini-tutorial, but I've replaced that with some default queries with new tasks etc. maybe the mini tutorial should be put back? If so, what should it cover?

Should there be a more "traditional" guided tour, with panels, arrows, popups etc. to guide people around?

Are there big blockers beyond that? I've heard the comment that the need to write Lua code to tweak the config is quite a hurdle and I can completely see that. Would having a more traditional Configuration UI be helpful?

Any other ideas? What did you run into early on?

All great things are not easy to find and take time to learn))) As a newcomer here I take this for granted and am ready to spend time reading through the glossary (after I realized there is one)))

So the easiest thing to do (IMHO) would be to make a silverbullet.md-wide table of contents. So it is like a documentation site all techies are used to. If there is one, please don't throw tomatoes at me and just give me a link.

The video tutorials are another great way to onboard. Your's are great and a pleasure to watch. The only "downside" is you're obviously an intelligent and structured person. And go from basics to more advanced slowly and gradually. A more use-case based shorter marketing-style videos could accompany those thorough tutorials focusing on features. I would love to see those. And just maybe the community could help with them.

As a rather recent joiner of the Silverbullet community, let me try to summarize my onboarding:

  • I thought Silverbullet was pretty self-explanatory, especially if you come from Obsidian, or in my case, LogSeq and SiYuan.
  • The LIQ query language was pretty easy to understand. I never managed to understand the LogSeq query language, but with Silverbullet LIQ I had no issue.
  • I watched the tutorial video's and found them quite useful
  • I'm still struggling to figure out keyboard short-cuts. I'll admit I'm a chronic mouse user, but I can't remember much more than ctrl-k and ctrl-s. And assigning a new shortcut still has me stumped.
  • I struggled for quite some time to get a decent theme in place. This might be an area to consider polishing the desktop app a bit and offering some out-of-the-box themes.
  • I also struggled to figure out where to put my Lua and space-style code (and I was very confused by v1 and v2 differences (on the forum primarily).

I think a guided tour is a good idea, but will always be a bit superficial (this button, that button). For me, this was not the hard part in getting started with Silverbullet.

I think it might be useful to break the introduction down into separate topics, so people can dive in on their own:

  • How to manage and structure notes in Silverbullet and how not to lose notes (incl how to install the tree view or the document explorer). Obviously, there are lot's of ways to do this, but some initial guidance would be useful
  • Defining buttons and slash-command (maybe keyboard shortcuts as well)
  • Installing libraries
  • Manage tasks ( (again, there are multiple ways, but helps to get ppl started)
  • Writing queries and structuring your data to be query-able.

These topics should be structured by explanation and examples, and, potentially tutorial videos.

Furthermore, it would be useful to clean up or clarify the forum for v1 stuff. This felt like a significant hurdle for me in fine-tuning Silverbullet initially.

Perhaps comb through this forum for some common things to point out? What springs to mind are questions liking hiding frontmatter, customising the default widgets, maybe some basic CONFIG stuff?

I was totally blown away by the idea that you can dynamically view content using queries. Then I watched a few videos that explain SilverBullet really well (really great videos!) and it became clear to me that I should switch my note-taking system. It consisted of AsciiDoc files. But almost all note-taking systems only work with Markdown, so I first had to convert them from AsciiDoc to Markdown using downdoc, which works quite well.

Installation was also easy with Docker on a Synology. But then came the requirement for HTTPS: I first had to familiarize myself with HTTPS, reverse proxies, etc., and eventually ended up with Tailscale. Then I was able to get started, but had to do everything with the mouse because I had no idea how to bring up the pickers. For other commands, shortcuts are displayed when you search for them—that’s a brilliant solution. Then I found a “plugin” that let you display shortcuts. However, some of the shortcuts don’t work on a German keyboard. In particular, “Ctrl/Cmd + /” doesn’t work because “/” isn’t a dedicated key on the German keyboard—it’s Shift-7. So I had to figure out how to redefine shortcuts so that I could eventually open the Command Picker without a mouse.

Then I also discovered that treeview and Silversearch exist. Something like this could be standard, and during onboarding, you could suggest them as recommended plugins and immediately demonstrate how to integrate plugins.

The next hurdle was importing existing files into SilverBullet. My problem: they had a syntax like this: aaa.bbb.ccc.md, to represent virtual hierarchies. That doesn’t work in SilverBullet, so I had to rename everything.

Next hurdle: working on a smartphone. SilverBullet uses shortcuts, but working with them on mobile is quite difficult. With Silversearch, you can at least find content. Treeview only works to a limited extent, since the font on the smartphone is very large and you therefore never see the entire filenames.

Ultimately, I set up a Syncthing process to have the space available in parallel on the smartphone as well, so I can edit the Markdown files in parallel with Markor.

And so I’m now working my way through it step by step. Now I’m trying to understand why it’s recommended to include page tags in frontmatter instead of using simple tags, even though simple tags like #abc immediately become a link, have autocomplete, etc.

I really like the idea behind Silverbullet, and it’s definitely worth taking the time to learn how to use it. It’s truly an excellent and well-designed piece of software.

update:
I completely forgot about another hurdle: SilverBullet supports Git, but Git has to be available in the container first. So I had to figure that out as well. It might be helpful to provide a few Docker Compose examples. Here’s mine:

version: "3.9"

services:
  silverbullet:
    image: zefhemel/silverbullet:latest
    container_name: silverbullet
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true

    # Start-Logik: Installiert Git, setzt globale Rechte & Identität, startet die App
    entrypoint: ["/bin/sh", "-c"]
    command: >
      "apk add --no-cache git && 
      git config --system --add safe.directory '*' && 
      git config --system user.name \"$$GIT_USER_NAME\" && 
      git config --system user.email \"$$GIT_USER_EMAIL\" && 
      exec /docker-entrypoint.sh"

    user: root 
    ports:
      - "3010:3000"

    environment:
      # Diese Variablen mĂĽssen in den Portainer-Stack-Einstellungen definiert sein
      - GIT_USER_NAME=${GIT_NAME}
      - GIT_USER_EMAIL=${GIT_EMAIL}
      - SB_AUTH=${SB_USER}:${SB_PASS}
      - TZ=${TZ}
      - PUID=1026
      - PGID=100
      - HOME=/space 

    volumes:
      - ${SB_SPACE_PATH}:/space
      - ${SB_GIT_PATH}:/gitserver

I gave it another thought and try to see it as an App, but the knowledge that Silverbullets is a Website and knowing how Silverbullet works behind the scene, is definitely influencing my judgement to see it as an native App. (So the problem might be my brain playing tricks on me), like you said, this might be due to using it so much (for the last 1,5 years) in the browser or as an installed PWA.

As a general thought, we don't need to reinvent the wheel. There are some many best practices, and i definitely don't want to send you down the "Onboarding workflow" rabbit whole, but there are a lots of great videos online too with Do's and Don'ts about onboarding techniques and best practices.
It doesn't need to be something complex or boring, maybe jusr a simple slideshow with 3-5 slides with

  • the main features
  • what PagePicker, CommandPicker, LibraryManager is and how to find & use them
  • how to create a new page
  • basic navigation
  • the CONFIG page (maybe the COFIG page should also already have some commented out settings examples, like ( change editor width!!!!, disable TOC,...))
  • etc.
    to help the user get started, which can be skipped or closed, or opt out from the beginning with "Don't show this again" for experienced users to skip it with one click after installing.

So this is what I'm working on (with initial iterations landing on edge somewhere this week): a new Configuration Manager. This will replace a few things:

  1. Having to manage configuration with Space Lua code (although it will actually maintain a space lua block automaticaly in CONFIG and round-trip between what's set there and in the UI), so technically it all works the same, it just puts a UI on top to manage it.
  2. The library manager "UI" (not very discoverable as it is)
  3. Legacy plug manager (already hidden and "ghosted" but technically still around)

As I have it in my mind right now it will be a more "classic" modal window with (initially) a few sections:

  1. Configuration a more "classic" UI for configuring options. The configuration options are dynamically pulled from what's defined with config.define with some additional information becoming part of a config.define schemas, like default values, human readable descriptions, categorization etc. So in effect imagine options like "enable TOC", linked mentions, linked tasks toggles, etc. In the future we can think of other common things like selecting fonts (wow). The cool thing about this is that it's dynamically built from config.define so not hardcoded. True to SilverBullet principles of flexibility and extensibility, but still usable for those not interested in writing Lua code (yet).
  2. Key bindings: lists all commands and their current bindings and allows them to override them by pressing the desired keyboard combos in question. I think this will resolve a major painpoint because it should make it much more transparent to users what keyboard shortcuts are going to work and which are not.
  3. Library manager: roughly the same functionality as right now (repo management, library management) but with a more traditional UI. The currently Library manager is a clever use of Space Lua, but not exactly great UX.

This will also allow for future expansion, such as making the action buttons configurable through a UI, or other more fancy things like custom tag definitions and a whole lot more super powerful features that are hardly discoverable right now. Maybe a theme manager some day.