This is a slowly growing list of annotations for blocks in Makecode, mostly to document these for myself whenever I need to write another extensions.

Working Annotations

These are annotations that I have seen work in practice.

Namespace Properties

//% color="#BC986A" icon="\uf0ea"
Change the colour and icon for the namespace - the icon appears to be most valid unicode characters…

Basic Block Properties

Block Body Text
//% block="block text here"
This will replace the default generated block text with the supplied text.

Menu Groups
//% group="Buttons"
This does not require that the groups be predefined in the namespace.

Place Parameters in the Body Text
//% block="on ClipBit button $button pressed"
Replace $-prefix words with their parameter from the function.
Note that enums will be rendered as their names, rather than their values.

Advanced Blocks - Menu UI
//% advanced="true"
Move the block to the more section below the main section in the extension menu.

Parameter Render Options

Boolean Switches
//% on.shadow="toggleOnOff"
Sets the parameter ‘on’ to use the toggle on/off UI rather an a variable slot

Expandable Blocks (Hidden Parameters)
//% block="set ClipBit $display display to $value || as $style"
The double-bar || indicates the point that the block UI will be split, and replaced with an expander + icon.

Properties for Event Handlers

Allow Dragging of Parameters
//% draggableParameters="reporter"

Moving Between Languages

Shims
//% shim=ClipBit::sendLogViaSerial
Map the exported function annotated with this to the C++ call defined in the shim. Note that this doesn’t make a block by itself, and just exposes the call to Typescript.
If the function in Typescript has a body, this will be used in the sim.

Non-working Annotations

These are annotations that don’t seem to work correctly for Makecode extensions

Grid Picker

//% name.fieldEditor="gridpicker"
//% name.fieldOptions.columns=4
//% name.fieldOptions.tooltips="false"
//% name.fieldOptions.width="250"

This (as seen in pxt-microbit here) seems to enumerate enum values and generate a grid of buttons rather than the usual dropdown, except that it doesn’t work for extensions? Specifying these paramters will result in the block not having any parameter for the user to select at all!

Updated 5/2/2024

If you don’t actually want to have a block show up, but need the c++ shim to be generated, the correct way now seems to be to include //% as a comment before the methods you want to export.

With no directives, this just generates the shims and makes the compiler happy again.