Macros

The following macros are custom extensions to markdown.

Checkboxes in bullet points

Use * [ ] to create a bullet point with a square and * [x] for a checked bullet point

  • unchecked bullet point
  • checked bullet point
  • a regular bullet point

avatar

### ~avatar [class]

[content]

### ~

Example: the blink lesson and it’s markdown source.

Inline button rendering

Use ``|primary button|`` or ``||secondary button||`` to render a button like element.

Inline code snippets

If an inline code snippet start with [ and ends with ], the doc engine will try to render it as a block. It must contain a valid API call to the desired block.

To change the inline code snippet color to reflect the namespace color, use this format:

``|namespace.block name|``

Code snippets

To avoid screenshot hell, PXT automatically renders code snippets to blocks or javascript. This is done by specifying a language on code blocks.

dependencies

You need declare the packages required to load your snippet, unless they are part of the default empty template. Simple provide a list of package name using the package macro.

```package
microbit-devices
microbit-bluetooth
```

blocks

The blocks language renders a JavaScript snippet into blocks and provide a simulator if needed.

```blocks
basic.showNumber(5)
```

Example: the forever reference doc and it’s markdown source.

project

The project language is similar to blocks but renders a published project.

```project
twejlyucio
```

sig

The sig displays a signature of the first function call in the snippet.

```sig
basic.showNumber(5)
```

Example: the forever reference doc and it’s markdown source.

cards

The cards language displays a code card for each function call.

```cards
basic.showNumber(0);
basic.showLeds(`
. . . . .
. . . . .
. . # . .
. . . . .
. . . . .
`);
basic.showString("Hello!");
basic.clearScreen();
```

Example: the basic reference doc and it’s markdown source.

namespaces

The namespaces language display a code card for the first symbol of each namespace.

```namespaces
basic.showNumber(0);
input.onButtonPressed(() => {});
```

Example: the reference namespaces doc and it’s markdown source.

block

The block language renders a JavaScript snippet into blocks without any simulator.

```block
basic.showNumber(5)
```

javascript

If you need a rendering of typescript, javascript code, specify the language as typescript

```typescript
let x = 0;
```

codecard

Renders one or more codecards as JSON into cards

```codecard
[{ 
    "title": "A card", 
    "url": "...." 
}, {
    "title": "Another card", 
    "url": "...." 
}]
```

ignore

Append -ignore to any of the above to ignore a snippet in automated testing:

```typescript-ignore
// You can include illegal TS in here, e.g. to document syntax errors
callFunction(;
```