MakeCode has several custom macros that extend regular markdown. These provide extra style features and code / blocks rendering in the document pages.

The following macros are the MakeCode custom extensions to markdown.

Checkboxes in bullet points

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

Checked bullets

  • unchecked bullet point
  • checked bullet point
* [ ] unchecked bullet point
* [x] checked bullet point

Regular bullets

  • a regular bullet point
* a regular bullet point


MakeCode targets have avatar icons that help express a more personalized message to a user. The avatar icon is specified by its class name.

Hi! Writing docs for MakeCode is great!

### ~avatar [class]


### ~

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

Message Boxes

Message boxes bring special attention to an idea or to something that the user must take note of. There are several types of message boxes.


Hint Title


### ~hint

#### Hint Title

### ~


Tutorial hints accept but do not require a closing #### ~ tag. They terminate automatically on the next heading with an equal or lesser level.

Hint Title


#### ~hint

##### Hint Title


Reminder Title


### ~reminder

#### Reminder Title

### ~


Alert Title


### ~alert

#### Alert Title

### ~


Tip Title


### ~tip

#### Tip Title

### ~


As a navigation aid, the button macro is used to move to another page within the target’s document tree.

NEXT: Tutorials

## ~button /writing-docs/tutorials

NEXT: Tutorials

## ~

Inline button rendering

Use inline buttons to render a button like element. These aren’t linked to any action, they just display like buttons.

|primary button|

||secondary button||

``|primary button|``

``||secondary button||``

Namespace coloring

When a namespace specifier is included in the button text, the button will have the same color that is defined for showing blocks from that namespace. Use the namespace name separated with a :.


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.

Set your text variable like this: [let txt = "text"]

Set your text variable like this: ``[let txt = "text"]``

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


Code snippets

To avoid changing screenshots, PXT automatically renders code snippets to blocks or javascript. This is done by specifying a pseudo-language on a code section.


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.



You can specify required “features” for a given documentation page. In the case of a multi-board editor, MakeCode will match the feature set with existing boards.



The blocks “language” renders a JavaScript snippet into blocks and provides a simulator if needed.


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


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



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


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


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

. . . . .
. . . . .
. . # . .
. . . . .
. . . . .

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


The namespaces “language” displays a code card for the first symbol of each namespace.

input.onButtonPressed(() => {});

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


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



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

let x = 0;


If your editor supports Static Python, you can specify a TypeScript snippet to be rendered as Static Python using the spy macro.

let x = 0;


The ghost “language” causes addtional blocks to appear in the Toolbox during a tutorial step. This is used to provide additional block choices other than those matching the code snippet in a blocks section. The ghost blocks don’t render but serve to identify other blocks to add to the Toolbox choices.

let x = 0;


The template “language” is used to specify the initial code that appears in the workspace at the start of a tutorial. If there is no template block present in the tutorial, the default “new project” code will be used.

let x = 0;


To render one or more code cards as JSON into cards, use codecard.

    "title": "A card",
    "url": "...."
}, {
    "title": "Another card",
    "url": "...."


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

// You can include illegal TS in here, e.g. to showcase concepts/psuedocode
for (initialization; check; update) {


You can use typescript-invalid to showcase typescript that is incorrect:

// You can include illegal TS in here, e.g. to document syntax errors


You can use typescript-valid to showcase typescript that is correct:

// You can include any TS in here, e.g. to showcase correct syntax