@@ -47,6 +47,15 @@ end
Usage: `plainReplace(text, "arm64-v8a", "x86_64", 1)`
+# Space Lua tripwires
+
+- Space Lua APIs are camelCase: `space.readPage`, not `space.read_page`.
+- Use `return`; `print()` output is swallowed.
+- Don't chain `:gsub()` calls. `gsub` returns `(string, count)`, so reassign each step.
+- Don't use `query` as a variable or parameter name; it can parse as LIQ syntax.
+- The standard Lua `utf8` library is unavailable.
+- In LIQ, use explicit binding: `from p = ...`.
+
# Operations
```bash
@@ -92,10 +101,10 @@ space.writePage("Title", text)
return "done"
' | sb script
-# writing multi-line markdown with sb script
-# Use long-string delimiters [==[...]==] instead of [[...]] when the
-# markdown itself contains [[ or ]], which would prematurely close a
-# plain Lua long string and cause syntax errors.
+# writing multi-line Markdown with sb script
+# Use [==[...]==] instead of [[...]] when Markdown contains wiki links
+# or templates. If the content contains ]==], use a regular quoted string
+# with \n escapes or edit existing content with plainReplace instead.
echo '
local text = [==[
Some content with [[wiki links]] and ${template directives}.
@@ -103,6 +112,16 @@ Some content with [[wiki links]] and ${template directives}.
space.writePage("PageName", text)
return "done"
' | sb script
+
+# If multi-line content ends with ]] immediately before the closing ]==],
+# add a newline before the close and trim it off.
+echo '
+local text = [==[
+Ends with [[Page]]
+]==]:sub(1, -2)
+space.writePage("PageName", text)
+return "done"
+' | sb script
```
# Fetching SilverBullet docs
@@ -101,6 +101,31 @@ end
## Gotchas
+### Runtime output
+
+- `print()` output is swallowed in Runtime API — use `return`.
+
+### Space Lua parser and library quirks
+
+- APIs are camelCase, not snake_case: `space.readPage`, not `space.read_page`.
+- Don't chain `:gsub()` calls. `gsub` returns `(string, count)`, so reassign each step.
+- Don't use `query` as a variable or parameter name; it can parse as LIQ syntax.
+- The standard Lua `utf8` library is unavailable.
+- In LIQ, use explicit binding: `from p = ...`.
+
+### Long-bracket strings
+
+- Use `[==[...]==]` instead of `[[...]]` when Markdown contains wiki links or template syntax.
+- Content containing `]==]` closes a `[==[...]==]` literal early. Space Lua does not support higher levels like `[===[... ]===]`; use a regular quoted string with `\n` escapes or edit existing content instead of embedding it as a literal.
+- In multi-line strings, content ending with `]]` immediately before the closing `]==]` can break parsing. Add a newline before the close and trim it:
+ ```lua
+ local text = [==[
+ Ends with [[Page]]
+ ]==]:sub(1, -2)
+ ```
+
+### Editor/runtime commands
+
- `System: Reload` via `editor.invokeCommand` is **asynchronous**: it returns before the reload has actually completed. Any verification that must observe the post-reload runtime state should happen in a separate `execute_lua` call a moment later, not immediately after the reload in the same script.
```lua
local ok, err = pcall(editor.invokeCommand, "System: Reload")
@@ -110,8 +135,6 @@ end
## Notes
-- Always `return` values from lua_script because `print()` output is not captured
- Use `space.readRef("Page#Header")` to read specific sections
-- Use explicit variable binding in LIQ: `from p = ...` (not bare `from ...`)
- Namespace your functions: `myPlugin = myPlugin or {}; function myPlugin.doThing() ... end`
- Wiki-link syntax is `[[target|display]]` (not display|target), e.g. `[[tag:project|📌 project]]` shows "📌 project" linking to the tag:project virtual page