Matouš Jan Fialka
2aaa797bda
Lua `${...}` expression results are rendered using two parallel paths:
- **HTML path** (display path) for visual display in the editor and
- **Markdown path** (copy path) for the *copy button* output.
Every Lua value is classified as one of:
- **Scalar:** number, string, boolean, or `nil`
- **Empty table:** `{}`
- **Array:** a `LuaTable` with only sequential integer keys (no string keys)
- **Array of tables:** an array where every element is a `LuaTable`
- **Record:** a `LuaTable` with any string key (may also have integer keys)
Scalars are rendered as inline Markdown - wiki links, tags, bold, and
other inline syntax are resolved, `nil` renders as `<span data-empty>`.
Empty tables render as `<table data-table-empty>`.
An array of tables renders as a multi-row `<table>`. Column headers
are the union of all element keys. Each cell value recurses through
the same classification.
An array of scalars (or a mix of scalars and tables) renders as `<ul>`
with one `<li>` per element. Each item value recurses.
A record renders as a single-row `<table>` with one column per key.
Cell values recurse.
Every `<td>` carries `data-table-cell-type` and optionally
`data-table-cell-empty`. Every `<li>` carries `data-list-item-type` and
optionally `data-list-item-empty`. The outermost element carries
`data-type`. These attributes allow CSS styling of rendered widgets.
Nesting is **unlimited**. Tables inside cells, lists inside cells,
tables inside list items all render correctly in HTML.
Scalars render as plain text. Lua `nil` renders as `nil`. Empty tables
render as `*(empty table)*`.
An array of tables renders as a pipe-delimited Markdown table. Nested
values in cells are rendered as Lua literals via `toStringAsync()`
(e.g. `{1, 2, 3}` or `{a = 1}`), since Markdown table cells cannot
contain block-level content.
An array of scalars renders as a Markdown list (`- item`). When a list
item is itself multi-line (a sublist) it uses an empty bullet with
two-space indented content on the next line:
```
- 1
- 2
-
- nested 1
- nested 2
```
Nested tables or arrays **beyond the first list nesting** level are
rendered as Lua literals.
A record renders as a single-row Markdown table.
Column headers follow the order returned by `LuaTable.keys`: string keys
in their insertion order, followed by integer keys in ascending order.
For example, `{a = 1, b = 2, 3, d = 4}` produces columns `a
| b | d | 1`. This is consequence of `LuaTable` storing string keys
and the array part separately (for performance).
Arrays mixing plain scalars and record-like tables (e.g. `{1, 2, 3,
{a=3}}`) were previously rendered as a single flat table due to an
internal JS conversion (`toJS`). They now render as a list, with record
elements shown as nested tables - which more accurately reflects their
Lua structure. This is the only divergence from the original
presentation.
To restore the old tabular layout, wrap all elements as records with
a consistent key:
```lua
-- Before (was a flat table, now a list with nested table):
${{1, 2, 3, {a=3}}}
-- After (explicit records, renders as a table):
${{{value=1}, {value=2}, {value=3}, {a=3}}}
```
Signed-off-by: Matouš Jan Fialka <mjf@mjf.cz>
SilverBullet
SilverBullet is a Programmable, Private, Browser-based, Open Source, Self Hosted, Personal Knowledge Management Platform.
Yowza! That surely is a lot of adjectives to describe a browser-based Markdown editor programmable with Lua.
Let’s get more specific.
In SilverBullet you keep your content as a collection of Markdown Pages (called a Space). You navigate your space using the Page Picker like a traditional notes app, or through Links like a wiki (except they are bi-directional).
If you are the writer type, you’ll appreciate SilverBullet as a clean Markdown editor with Live Preview. If you have more of an outliner personality, SilverBullet has Outlining tools for you. Productivity freak? Have a look at Tasks. More of a database person? You will appreciate Objects and Queries.
And if you are comfortable programming a little bit — now we’re really talking. You will love dynamically generating content with Space Lua (SilverBullet’s Lua dialect), or to use it to create custom Commands, Page Templates or Widgets.
Much more detail can be found on silverbullet.md
Installing SilverBullet
Check out the instructions.
Developing SilverBullet
SilverBullet's frontend is written in TypeScript and built on top of the excellent CodeMirror 6 editor component. Additional UI is built using Preact. ESBuild) running through Deno is used to build both the front-end.
The server backend is written in Go.
If you're considering contributing changes, be aware of the LLM use policy.
Code structure
client/: The SilverBullet client, implemented with TypeScriptserver/: The SilverBullet server, written in Goplugs: Set of built-in plugs that are distributed with SilverBulletlibraries: A set of libraries (space scripts, page templates, slash templates) distributed with SilverBulletplug-api/: Useful APIs for use in plugslib/: Useful libraries to be used in plugssyscalls/: TypeScript wrappers around syscallstypes/: Various (client) types that can be references from plugs
binplug_compile.tsthe plug compiler
scripts/: Useful scriptswebsite/: silverbullet.md website content
Requirements
It's convenient to also install air for development, this will automatically rebuild both the frontend and backend when changes are made:
go install github.com/air-verse/air@latest
Make sure your $GOPATH/bin is in your $PATH.
To build everything and run the server:
air <PATH-TO-YOUR-SPACE>
Alternatively, to build:
make
To run the resulting server:
./silverbullet <PATH-TO-YOUR-SPACE>
Useful development tasks
# Clean all generated files
make clean
# Typecheck and lint all code
make check
# Format all code
make fmt
# Run all tests
make test
Build a docker container
Note, you do not need Deno nor Go locally installed for this to work:
docker build -t silverbullet .
To run:
docker run -p 3000:3000 -v <PATH-TO-YOUR-SPACE>:/space silverbullet