Website docs refactoring (Lua, mostly)

Author: zefhemel

STYLE.md

@@ -0,0 +1,128 @@
+A few notes on coding conventions used in this project.
+
+# Tooling
+
+Run these commands to perform type and style checks and automatically reformat code based on conventions:
+
+```bash
+make check           # Type check + lint frontend and backend
+make fmt             # Format all code
+```
+
+# Code Style Guidelines
+
+## TypeScript (client and plugs)
+
+### Import Organization
+
+```typescript
+// Use relative imports by default (include .ts extension)
+import { Space } from "./space.ts";
+// Use `type` for type-only imports (part of the lint rules)
+import type { Command } from "./types/command.ts";
+
+// Use package-prefixed absolute when available (defined in deno.json)
+import { sleep } from "@silverbulletmd/silverbullet/lib/async";
+```
+
+### TypeScript Conventions
+* Use `type` over `interface` for object shapes
+* Use `type` for unions and complex types
+* Always type function parameters explicitly
+* Type return values for public APIs
+* Let TypeScript infer obvious variable types
+* Use `any` for error objects in catch blocks
+
+
+### Naming Conventions
+- **Variables & functions:** `camelCase`
+- **Classes:** `PascalCase`
+- **Files:** `snake_case.ts` (e.g., `http_space_primitives.ts`)
+- **Test files:** `*.test.ts` alongside source files
+- **Types:** `PascalCase` (e.g., `PageMeta`, `SpacePrimitives`)
+- **Constants:** `camelCase`
+
+
+### Testing Patterns
+TypeScript tests run with Deno.
+
+**Test structure:**
+```typescript
+Deno.test("Test description in plain English", async () => {
+  // Setup
+  const kv = new MemoryKvPrimitives();
+  const space = new Space(new DataStoreSpacePrimitives(kv), eventHook);
+  
+  // Execute
+  await space.writePage("test", testPage);
+  
+  // Assert
+  assertEquals(await space.readPage("test"), testPage);
+});
+```
+
+**Assertions:**
+```typescript
+import { assertEquals, assertNotEquals } from "@std/assert";
+
+assertEquals(actual, expected);
+assertNotEquals(actual, notExpected);
+```
+
+**Test configuration:**
+```typescript
+Deno.test("Test with options", {
+  sanitizeResources: false,
+  sanitizeOps: false,
+}, async () => {
+  // test code
+});
+```
+
+### Comments & Documentation
+
+Use JSDoc for public APIs:
+```typescript
+/**
+ * Lists all pages (files ending in .md) in the space.
+ * @param unfiltered - Whether to include filtered pages
+ * @returns A list of all pages represented as PageMeta objects
+ */
+export function listPages(unfiltered?: boolean): Promise<PageMeta[]> {
+  return syscall("space.listPages", unfiltered);
+}
+```
+
+Inline comments:
+* In case of doubt: add comments around the _why_ of the code (not what)
+* Add TODO comments for known issues
+
+```typescript
+// Note: these events are dispatched asynchronously (not waiting for results)
+this.eventHook.dispatchEvent(...);
+
+// TODO: Clean this up, this has become a god class
+export class Client {
+```
+
+### Code Patterns
+
+**Definite assignment for late initialization:**
+```typescript
+class Client {
+  space!: Space;        // Initialized in init()
+  editorView!: EditorView;
+}
+```
+
+**Destructuring:**
+```typescript
+const { name, def } = command;
+const { text, meta } = await this.space.readPage(name);
+```
+
+## Go (server)
+Follow common Go conventions. `make fmt` also reformats Go code.
+
+## Lua (libraries)
+See `website/Space Lua/Conventions`

website/API/dom.md

@@ -0,0 +1,62 @@
+An API to easily build DOM objects through the magic of Lua meta tables.
+
+# Usage
+
+```lua
+-- any HTML tag can be used here
+dom.span {
+  -- tag attributes can be set like this:
+  class = "my-class",
+  id = "my-id",
+  -- Plain text body elements can be added like this
+  "Span content",
+  -- And elements can be nested
+  dom.strong { "I am strong" },
+  -- Widgets can also be embedded
+  widget.html "<b>Bold</b>",
+  widget.html(dom.marquee { "nested widget" })
+}
+```
+
+Example:
+${widget.html(dom.marquee {
+  "I'm in a ",
+  dom.span {
+    style="color:red;",
+    "marquee"
+  }
+})}
+
+# API
+## dom.* {attribute1=value, attribute2=value, childElement1, childElement2}
+Renders a HTML DOM.
+
+* `attribute=value` key/value mappings are translated to HTML DOM attribtutes.
+* Plain text elements such as `"Hello **world**"` are parsed and rendered as markdown translated to HTML.
+* DOM elements (for instance those resulting from additional `dom.*` calls) are injected in place.
+* [[API/widget|widgets]] are rendered in place.
+
+For instance:
+
+```lua
+dom.span {
+  class = "class-attribute",
+  dom.span {
+    "A first nested span"
+  },
+  dom.span {
+    "A second nested span"
+  },
+}
+```
+
+Would be roughly equivalent to the following HTML:
+
+```html
+<span class="class-attribute">
+  <span>A first nested span</span>
+  <span>A second nested span</span>
+</span>
+```
+
+This API is implemented using Lua metatables, its implementation lives here: [[^Library/Std/APIs/DOM]]

website/API/tag.md

@@ -6,6 +6,9 @@ Enables customization of [[Tag|tags]] and its [[Object|objects]] in a few ways:
 * Change how objects are indexed in the [[Object Index]]
 * Tweak styling of tags in the editor using [[Space Style]]
 
+> **success** Success
+> Put all your `tag.define` calls in your [[CONFIG]] page so that they will be picked up during the index process.
+
 # API
 ## tag.define(spec)
 Defines a tag explicitly.

website/API/widget.md

@@ -0,0 +1,58 @@
+APIs to define widgets in SilverBullet, often used through [[Space Lua#Expressions]].
+
+# Widget types
+## Markdown widgets
+When setting a `markdown` key, or using the `widget.markdown` API, a markdown-based widget can be created.
+
+Example:
+
+```space-lua
+function helloWorld(name)
+  return widget.markdown("Hello world, *" .. name .. "*!")
+end
+```
+
+Can be used as follows:
+
+${helloWorld("Pete")}
+
+## DOM widgets
+To render a custom HTML-based widget, use the [[API/dom]] elements passed as an argument to `widget.html`:
+
+```space-lua
+function marquee(text)
+  return widget.html(dom.marquee {
+    class = "my-marquee",
+    onclick = function()
+      editor.flashNotification "You clicked me"
+    end,
+    text
+  })
+end
+```
+
+We can combine this with some [[Space Style]] to style it:
+
+```space-style
+.my-marquee {
+  color: purple;
+}
+```
+
+This can be used as follows:
+${marquee "Finally, marqeeeeeee!"}
+# API
+## widget.new(spec)
+To render a widget, call `widget.new` with a `spec` table setting any of the following keys:
+
+* `markdown`: Renders the value as markdown
+* `html`: Renders a HTML DOM as a widget. It is usually used in conjunction with the [[API/dom]] API.
+* `display`: Render the value either `inline` or as a `block` (defaults to `inline`).
+
+## widget.markdown(text)
+Shortcut for `widget.new { markdown = text }`
+
+## widget.html(htmlOrDOM)
+Shortcut for `widget.new { html = htmlOrDOM }`
+
+Usually used in conjunction with [[API/dom]].

website/CHANGELOG.md

@@ -22,18 +22,23 @@ Whenever a commit is pushed to the `main` branch, within ~10 minutes, it will be
   * `Page: Rename` keyboard shortcut removed
   * `Page: Rename Linked Page` keyboard shortcut removed
   * `Sync: Space` keyboard shortcut removed
+* Sync reliability work:
+  * Better indication whether your page is synced to the server: “Dirty state” (slightly tinted color of page name) is now aligned with actual synced-to-server state _unless_ the editor clearly indicates it is in offline mode (yellow top bar).
+  * Sync snapshots are now persisted after every file sync, reducing (and hopefully eliminating) edge cases where the sync engine is killed mid-sync (for whatever reason) and the snapshot becomes of sync with “reality”.
+  * The index status progress indicator (blue circle) should now be more reliably reflect the actual indexing status.
+* Tag schema updates:
+  * `pos` (present in link, item and some other tags) is now _deprecated_, use `range` instead
+  * `range` is a tuple of two numbers: _from_ and _to_ (e.g. `{0, 10}`) identify where the object appears in the page
 * Lua engine improvements (courtesy of [Matouš Jan Fialka](https://github.com/mjf)):
   * [Support for `<close>` attribute and __close metamethod](https://github.com/silverbulletmd/silverbullet/commit/9419cdcd9be61908330e1dce68a9156dbb911d23)
   * [Better arithmetic error messages](https://github.com/silverbulletmd/silverbullet/commit/5a20a5f8f476a98172609e80c799cd1d83765585)
   * [Refactor of control flow (performance)](https://github.com/silverbulletmd/silverbullet/commit/e5b4c8feb22a44cb4b22b3a77f9f2ed21dd09297)
   * [Improved numeric type semantics](https://github.com/silverbulletmd/silverbullet/pull/1803)
 * Lua APIs:
   * [[API/table#table.select(table, keys...)]] (non-standard in Lua) API, convenient to use in [[Space Lua/Lua Integrated Query]] `select` clauses, see example in docs.
-* Sync reliability work:
-  * Better indication whether your page is synced to the server: “Dirty state” (slightly tinted color of page name) is now aligned with actual synced-to-server state _unless_ the editor clearly indicates it is in offline mode (yellow top bar).
-  * Sync snapshots are now persisted after every file sync, reducing (and hopefully eliminating) edge cases where the sync engine is killed mid-sync (for whatever reason) and the snapshot becomes of sync with “reality”.
-  * The index status progress indicator (blue circle) should now be more reliably reflect the actual indexing status.
 * Library manager: SilverBullet now navigates to library page after installing one.
+* Styling changes:
+  * Attribute names and values ([key: value] notation) now get different CSS classes in the editor: `sb-attribute-name` for names and `sb-attribute-value` for values.
 * New `Page: Create Under Cursor` command, useful to pre-create an aspiring page link. Put your cursor in a wiki link to a non-existing page, and hit `Cmd-Shift-Enter` (`Ctrl-Shift-Enter`) to create it (empty) without navigating there.
 * Authentication:
   * How long “remember me” works is now configurable (by [Metin Yazici](https://github.com/silverbulletmd/silverbullet/pull/1796)) via [[Install/Configuration]] and more reliably persisted.

website/Object Index.md

@@ -7,7 +7,7 @@ You interact with it in a few ways:
 
 # Indexing
 ## Initial indexing process
-When you launch a fresh client for the first time, the object index will be built from scratch. Depending on the size of your space this can take anything between a few seconds and minutes. If the process takes longer than a few seconds, you will see progress with a blue status circle. Until this initial indexing process finishes, you will notice that things like [[Space Lua/Widget]] and [[Space Lua/Lua Integrated Query]] are not yet rendered, this is to avoid errors and invalid data.
+When you launch a fresh client for the first time, the object index will be built from scratch. Depending on the size of your space this can take anything between a few seconds and minutes. If the process takes longer than a few seconds, you will see progress with a blue status circle. Until this initial indexing process finishes, you will notice that things like [[API/widget|Widgets]] and [[Space Lua/Lua Integrated Query]] are not yet rendered, this is to avoid errors and invalid data.
 
 After the initial index process, the index will be kept up-to-date incrementally.
 

website/Object/space-lua.md

@@ -0,0 +1 @@
+Every `space-lua` block across your space is indexed with the `space-lua` tag. Upon client boot (or after using `System: Reload`), all space lua scripts are executed in sequence.

website/SilverBullet.md

@@ -9,7 +9,7 @@ In SilverBullet you keep your content as a collection of [[Markdown]] [[Page|Pag
 
 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 [[Outlines|Outlining]] tools for you. Productivity freak? Have a look at [[Task|Tasks]]. More of a **database** person? You will appreciate [[Object|Objects]] and [[Space Lua/Lua Integrated Query|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 [[Command|Commands]], [[Page Template|Page Templates]] or [[Space Lua/Widget|Widgets]].
+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 [[Command|Commands]], [[Page Template|Page Templates]] or [[API/widget|Widgets]].
 
 # Programmable notes
 Dynamically generating content, _programmable notes_... why would you want that, and how does it work?