63 lines
1.8 KiB
Markdown
63 lines
1.8 KiB
Markdown
---
|
|
description: API to define custom renderers for fenced code blocks from Space Lua
|
|
tags: meta/api
|
|
---
|
|
API to define custom renderers for fenced code blocks (code widgets) from Space Lua.
|
|
|
|
# API
|
|
|
|
## codeWidget.define(def)
|
|
Registers a renderer for fenced code blocks of a given language.
|
|
|
|
Available keys:
|
|
|
|
* `language`: The language of the fenced code block to render (the string right after the opening ```` ``` ````).
|
|
* `render`: A callback `function(bodyText, pageName)` that receives the body text of the code block and the name of the page it appears on. It returns the same kind of value as a `${...}` directive: either a string (rendered as markdown), or a widget table such as one created with [[^Library/Std/APIs/Widget|widget.new{}]] or `widget.sandbox{}`.
|
|
|
|
Lua code widgets render through the same pipeline as `${...}` directives, so they get the same Copy/Edit/Reload bar. The Copy button copies the rendered `markdown`.
|
|
|
|
Example rendering a string as markdown:
|
|
|
|
```lua
|
|
codeWidget.define {
|
|
language = "greet",
|
|
render = function(bodyText, pageName)
|
|
return "Hello, **" .. bodyText .. "**! (on page " .. pageName .. ")"
|
|
end
|
|
}
|
|
```
|
|
|
|
A code block like this:
|
|
|
|
```greet
|
|
world
|
|
```
|
|
|
|
would then render as "Hello, **world**! (on page ...)".
|
|
|
|
Example producing a rich widget (a mermaid diagram):
|
|
|
|
```lua
|
|
codeWidget.define {
|
|
language = "mermaid",
|
|
render = function(bodyText)
|
|
return widget.html(dom.div {
|
|
class = "mermaid",
|
|
bodyText
|
|
})
|
|
end
|
|
}
|
|
```
|
|
|
|
# Implementation
|
|
Most of the heavy lifting happens in SB itself. This is just a thin wrapper around the config object API: it writes the definition into `config` under `codeWidgets.<language>`.
|
|
|
|
```space-lua
|
|
-- priority: 99
|
|
codeWidget = codeWidget or {}
|
|
|
|
function codeWidget.define(def)
|
|
config.set({"codeWidgets", def.language}, def)
|
|
end
|
|
```
|