Preparing for an initial release
This commit is contained in:
Zef Hemel
@@ -0,0 +1,3 @@
|
||||
data.db
|
||||
_plug
|
||||
_trash
|
||||
@@ -0,0 +1,14 @@
|
||||
This file lists all plugs that SilverBullet will load. Run the `Plugs: Update` command to update and reload this list of plugs.
|
||||
|
||||
```yaml
|
||||
- builtin:core
|
||||
- builtin:emoji
|
||||
- builtin:ghost
|
||||
- builtin:git
|
||||
- builtin:github
|
||||
- builtin:markdown
|
||||
- builtin:mattermost
|
||||
- builtin:plugmd
|
||||
- builtin:query
|
||||
- builtin:tasks
|
||||
```
|
||||
@@ -0,0 +1,55 @@
|
||||
# Silver Bullet
|
||||
Silver Bullet (SB) is a highly extensible, open source **personal knowledge playground**. At its core it’s a Markdown-based writing/note taking application that stores _pages_ (notes) as plain markdown files in a folder referred to as a _space_. Pages can be cross-linked using the `[[link to other page]]` syntax. This makes it a simple tool for [Personal Knowledge Management](https://en.wikipedia.org/wiki/Personal_knowledge_management). However, once you leverage its various extensions (called _plugs_) it can feel more like a _knowledge playground_, allowing you to annotate, combine and query your accumulated knowledge in creative ways, specific to you.
|
||||
|
||||
So what is it SB _really_? That is hard to answer. It can do a ton of stuff out of the box, and I’m constantly finding new use cases. It’s like... a silver bullet!
|
||||
|
||||
Here’s how I use it today (but this has grown significantly over time):
|
||||
|
||||
* Basic note taking, e.g. meeting notes, notes on books I read, blogs I read, podcasts I listen to, movies I watch.
|
||||
* Getting a quick glance at the work people in my team are doing by pulling data from our 1:1 notes, recent activity on Github (such as recent pull requests) and other sources.
|
||||
* Writing:
|
||||
* [My blog](https://zef.plus) is published via SB’s [Ghost](https://ghost.org) plugin.
|
||||
* An internal newsletter that I write is written in SB.
|
||||
* Performance reviews for my team (I work as a people manager) are written and managed using SB (for which I extensively use SB’s meta data features and query that data in various ways).
|
||||
* A custom SB plugin aggregates data from our OpsGenie account every week, and publishes it to our [Mattermost](https://mattermost.com/) instance.
|
||||
* It powers part of my smart home: I wired HomeBridge webhooks up to custom HTTP endpoints exposed by my custom smart home SB plug.
|
||||
|
||||
That’s a pretty crazy wide range of use cases!
|
||||
|
||||
I know, right?
|
||||
|
||||
**Disclaimer:** Silver Bullet is under heavy development and significant changes under the hood happen constantly. It’s also low on automated tests and documentation. All this will improve over time. I’ll do better, I promise.
|
||||
|
||||
[[🤯 Features]]
|
||||
[[💡 Inspiration]]
|
||||
[[🔌 Plugs]]
|
||||
[[🔨 Development]]
|
||||
|
||||
## Installing and running Silver Bullet
|
||||
To run a release version, you need to have a recent version of npm (8+) and node.js (16+) installed as well as some basic build infrastructure (make, cpp). Silver Bullet has only been tested on MacOS and Linux thus far.
|
||||
|
||||
To install and run, create a folder for your pages (can be empty or an existing folder with `.md` files) and run:
|
||||
|
||||
npx @silverbullet/server <path-to-folder>
|
||||
|
||||
Optionally you can use the `--port` argument to specify a HTTP port (defaults to `3000`) and you can pass a `--password` flag to require a password to access. Note this is a rather weak security mechanism, so it’s recommended to add additional layers of security on top of this if you run this on a public server somewhere (at least add TLS). Personally I run it on a tiny Linux VM on my server at home, and use a VPN (Tailscale) to access it from outside my home.
|
||||
|
||||
## Roadmap
|
||||
More details on the [[🗺️ Roadmap]] page.
|
||||
<!-- #query task render "template/tasks" -->
|
||||
* [ ] [[🗺️ Roadmap@34]] Persistent recent commands (saved between sessions)
|
||||
* [ ] [[🗺️ Roadmap@92]] Add ==marker== syntax
|
||||
* [ ] [[🗺️ Roadmap@120]] Two finger tap gesture to bring up command palette
|
||||
* [ ] [[🗺️ Roadmap@177]] Change indent level command
|
||||
* [ ] [[🗺️ Roadmap@212]] Keyboard shortcuts for specific notes (e.g. `index` note)
|
||||
* [ ] [[🗺️ Roadmap@276]] RevealJS slides plug
|
||||
* [ ] [[🗺️ Roadmap@303]] Pinned notes and actions?
|
||||
* [ ] [[🗺️ Roadmap@335]] Template for deadline, with 📅 emoji and perhaps defaulting to today?
|
||||
* [ ] [[🗺️ Roadmap@411]] Use webauthn https://www.npmjs.com/package/webauthn
|
||||
* [ ] [[🗺️ Roadmap@469]] Proper sign up and login
|
||||
* [ ] [[🗺️ Roadmap@500]] Data store pagination API
|
||||
* [ ] [[🗺️ Roadmap@532]] Hashtag plug:
|
||||
* [ ] [[🗺️ Roadmap@656]] Extract `MarkdownEditor` component.
|
||||
* [ ] [[🗺️ Roadmap@725]] PUT page with `If-Last-Modified-Before` type header. Rejects if not matching. Client creates a revision, navigates to it.
|
||||
* [ ] [[🗺️ Roadmap@858]] Put retries exponential back off
|
||||
<!-- /query -->
|
||||
Vendored
+3
@@ -0,0 +1,3 @@
|
||||
{{#each .}}
|
||||
* [{{#if done}}x{{else}} {{/if}}] [[{{page}}@{{pos}}]] {{name}}
|
||||
{{/each}}
|
||||
@@ -0,0 +1,3 @@
|
||||
Inspiration for Silver Bullet comes primarily from [Obsidian](https://obsidian.md/) and its various plugs (the work-in-progress plugs around querying and tasks are inspired by Obsidian’s tasks and dataview plugins), but also [Roam Research](https://roamresearch.com/) was an inspiration.
|
||||
|
||||
Why start something new? Neither of these tools are open source, and they make some different choices, specifically on how extensibility is implemented — more on the differences some time in the future.
|
||||
@@ -0,0 +1,21 @@
|
||||
Silver Bullet at its core is bare bones in terms of functionality, most of its power it gains from **plugs**.
|
||||
|
||||
Plugs are an extension mechanism (implemented using a library called `plugos` that runs plug code on the server in a sandboxed v8 node.js process, and in the browser using web workers). Plugs can hook into SB in various ways: plugs can extend the Markdown parser and its syntax, define new commands and keybindings, respond to various events triggered either on the server or client side, as well as run recurring and background tasks. Plugs can even define their own extension mechanisms through custom events. Each plug runs in its own sandboxed environment and communicates with SB via _syscalls_ that expose a vast range of functionality. Plugs can be loaded, unloaded and updated without having to restart SB itself.
|
||||
|
||||
Examples of functionality implemented as plugs:
|
||||
|
||||
* _Core functionality_ such as:
|
||||
* Navigation between pages by clicking or hitting `Cmd/Ctrl-Enter`
|
||||
* Page auto complete when using the `[[page link]]` syntax
|
||||
* Indexing of cross-page links and automatically updating all references to them when a page is renamed
|
||||
* Text editing commands such as bold (`Cmd/Ctrl-b`) and italics (`Cmd/Ctrl-i`) or quote or itemize entire sections.
|
||||
* Full text indexing and search
|
||||
* Slash commands such as `/today`, `/tomorrow` and `/meta` (to insert page meta data)
|
||||
* Emoji auto complete using the `:emoji:` syntax
|
||||
* An embedded query language that can be used to query various sets of indexed entities, such as:
|
||||
* Tasks using the Markdown task syntax
|
||||
* Page backlinks
|
||||
* Page in your space and its meta data
|
||||
* Data objects embedded in your pages
|
||||
* Git integration
|
||||
* Github integration
|
||||
@@ -0,0 +1,38 @@
|
||||
## Stack
|
||||
Silver Bullet is written in [TypeScript](https://www.typescriptlang.org/) and built on top of the excellent [CodeMirror 6](https://codemirror.net/) editor component. Additional UI is built using React.js. [ParcelJS](https://parceljs.org/) is used to build both the front-end and back-end bundles. The server backend runs as a HTTP server on node.js using express.
|
||||
|
||||
## Development
|
||||
This [Silver Bullet repo](https://github.com/zefhemel/silverbullet) is a monorepo using npm's "workspaces" feature.
|
||||
|
||||
Requirements: node 16+ and npm 8+ as well as C/C++ compilers (for compiling SQLite, on debian/ubuntu style systems you get these via the `build-essential` package)
|
||||
|
||||
To run, after clone:
|
||||
|
||||
```shell
|
||||
# Install dependencies
|
||||
npm install
|
||||
# Run initial build (web app, server, etc.)
|
||||
npm run build
|
||||
# Again, to install the CLIs just built (plugos-bundler, silverbullet)
|
||||
npm install
|
||||
# Build built-in plugs
|
||||
npm run build-plugs
|
||||
# Launch server
|
||||
npm run server -- <PATH-TO-YOUR-SPACE>
|
||||
```
|
||||
|
||||
This `<PATH-TO-YOUR-SPACE>` can be any folder with markdown files, upon first boot SB will ensure there is an `index.md` file (root page) and `PLUGS.md` file (with default list of plugs to load). SB will also create a SQLite `data.db` file with various data caches and indices (you can delete this file at any time and use the `Space: Reindex` command to reindex everything).
|
||||
|
||||
Open SB at http://localhost:3000 If you're using a browser supporting PWAs, you can install this page as a PWA. This also works on iOS (use the "Add to homescreen" option in the share menu).
|
||||
|
||||
General development workflow:
|
||||
|
||||
Run these in separate terminals
|
||||
```shell
|
||||
# Runs ParcelJS in watch mode, rebuilding the server and webapp continuously on change
|
||||
npm run watch
|
||||
# Runs the silverbullet server
|
||||
npm run server
|
||||
# Builds (and watches for changes) all builtin plugs (in packages/plugs)
|
||||
npm run plugs
|
||||
```
|
||||
@@ -0,0 +1,22 @@
|
||||
Some things I want to work on:
|
||||
|
||||
* [ ] Persistent recent commands (saved between sessions)
|
||||
* [ ] Add ==marker== syntax
|
||||
* [ ] Two finger tap gesture to bring up command palette
|
||||
* [ ] Change indent level command
|
||||
* [ ] Keyboard shortcuts for specific notes (e.g. `index` note)
|
||||
* [ ] RevealJS slides plug
|
||||
* [ ] Pinned notes and actions?
|
||||
* [ ] Template for deadline, with 📅 emoji and perhaps defaulting to today?
|
||||
* [ ] Use webauthn https://www.npmjs.com/package/webauthn
|
||||
* [ ] Proper sign up and login
|
||||
* [ ] Data store pagination API
|
||||
* [ ] Hashtag plug:
|
||||
* Higlighting
|
||||
* Page indexing/item indexing
|
||||
* Tag completion
|
||||
* Query providers: ht-page ht-item
|
||||
* [ ] Extract `MarkdownEditor` component.
|
||||
* REST API safeguards:
|
||||
* [ ] PUT page with `If-Last-Modified-Before` type header. Rejects if not matching. Client creates a revision, navigates to it.
|
||||
* [ ] Put retries exponential back off
|
||||
@@ -0,0 +1,10 @@
|
||||
* **Free and open source** (MIT licensed)
|
||||
* **Distraction free** UI with [What You See is What You Mean](https://en.wikipedia.org/wiki/WYSIWYM) Markdown editing.
|
||||
* **Future proof**: stores all notes in a regular folder with markdown files, no proprietary file formats. While SB uses a SQLite database for indexes, this database can be wiped and rebuilt based on your pages at any time. Your Markdown files are the single source of truth.
|
||||
* **Run anywhere**: run it on your local machine, or install it on a server. You access it via your web browser (desktop or mobile), or install it as a PWA (giving it its own window frame and dock/launcher/dock icon).
|
||||
* **Keyboard oriented:** you can fully operate SB via the keyboard (on laptop/desktop machines as well as iPads with a keyboard):
|
||||
* Switch between pages using `Cmd-k` (Mac) or `Ctrl-k` (Linux/Windows)
|
||||
* Open the command palette using `Cmd-/` (Mac) or `Ctrl-/` (Linux/Windows)
|
||||
* Use slash commands by entering a `/` in your note’s text
|
||||
* Various plugs add additional keyboard shortcuts and auto completions like when entering `[[page links]]` and typing emoji via the `:lemon:` syntax.
|
||||
* **Extensible** through plugs (see below)
|
||||
Reference in New Issue
Block a user