Explain how "macros" work in djot

Makefile

@@ -2,6 +2,5 @@ VIMDIR?=~/.vim
 
 all: doc/syntax.html
 
-doc/syntax.html: doc/syntax.md
+doc/syntax.html: doc/syntax.md doc/syntax.css doc/code-examples.lua
 	pandoc --lua-filter doc/code-examples.lua $< -t html -o $@ -s --css doc/syntax.css --self-contained --wrap=preserve --toc --section-divs -Vpagetitle="Djot syntax reference"
-

doc/code-examples.lua

@@ -5,6 +5,14 @@ function renderdjot(txt)
 end
 
 function CodeBlock(el)
+  local lang = el.attr.classes[1]
+  if lang then
+    return {
+      pandoc.Div(
+      { pandoc.Div({pandoc.CodeBlock(el.text)}, {class=lang})
+      }, {class="example"})
+    }
+  end
   local rendered = renderdjot(el.text)
   return {
     pandoc.Div(

doc/syntax.css

@@ -212,3 +212,17 @@ ul.task-list{list-style: none;}
 .example code {
   font-size: 78%;
 }
+
+kbd {
+  background-color: #eee;
+  border-radius: 3px;
+  border: 1px solid #b4b4b4;
+  box-shadow: 0 1px 1px rgba(0, 0, 0, 0.2), 0 2px 0 0 rgba(255, 255, 255, 0.7) inset;
+  color: #333;
+  display: inline-block;
+  font-size: 0.85em;
+  font-weight: 700;
+  line-height: 1;
+  padding: 2px 4px;
+  white-space: nowrap;
+}

doc/syntax.md

@@ -781,6 +781,51 @@ See the [Epilogue][].
 # Epilogue
 ```
 
+## Syntax extensions
+
+Djot doesn't have macros or other built-in facilities to extend the syntax of
+the language. However, [divs](#div), [spans](#span), and
+[attributes](#block-attributes) allow achieving equivalent results by extending
+the way a djot document is converted to a target format.
+
+For example, djot doesn't have syntax for keyboard shortcuts like
+<kbd>ctrl</kbd> + <kbd>v</kbd>. Nevertheless, the appropriate semantics can be
+ascribed to spans with a `.kbd` class.
+
+By default, they will be rendered with `<span>` tags in HTML:
+
+```
+[ctrl + f]{.kbd}
+```
+
+By customizing the rendering, it's possible to change the output to the desired
+`<kbd>`:
+
+```html
+<kbd>ctrl</kbd> + <kbd>f</kbd>
+```
+
+For example, JavaScript implementation of djot allows overriding rendering of
+arbitrary elements:
+
+```ts
+{
+  span: (node: Span, r: HTMLRenderer) => {
+    if (hasClass(node, "kbd")) {
+      return getStringContent(node)
+        .split("+")
+        .map((key) => `<kbd>${key}</kbd>`)
+        .join("+");
+    }
+    return r.renderAstNodeDefault(node);
+  }
+}
+```
+
+Specific mechanisms for customizing rendering are implementation defined.
+However, all implementations are expected to provide facilities for customizing
+the output based on the Djot abstract syntax tree.
+
 ## Nesting limits
 
 Conforming implementations can impose reasonable limits on