pxt-calliope/docs/reference/js/markdown.md

Markdown Syntax

Syntax to create formatted text in Touch Develop. #docs #markdown

@parent td/comment

Markdown is a popular syntax used by developers to describe and annotate documents. Touch Develop supports a large subset of the markdown syntax, and adds a few new features. Markdown syntax applies to comments added using the Touch Develop editor.

Basic markdown syntax

Headings

Use #, ##, or ### at the beginning of a line to specify a heading:

• use # for heading 1
• use ## for heading 2
• use ### for heading 3

Bulleted lists

Use a * for a bullet:

* this is a bullet

Numbered lists

Type a number, a period, and a space before each item in a numbered list. Like this:

1. first item

2. second item

3. third item

The numbers in a numbered list appear as 1. in the Touch Develop editor, however, the numbers will update when the script is previewed or published.

Character formatting

Use a single * for italic and ** for bold:

*italic* => italic

**bold** => bold

Links

• to add a link, type the URL: http://touchdevelop.com => http://touchdevelop.com
• to specify link text (instead of the URL), put the link text in [ ] brackets and the link in ( )

For example:

[TouchDevelop website](http://touchdevelop.com) => TouchDevelop website

Columns

To format text into columns, insert ### ~column at the start of each column and ### ~ at the end of the column.

Touch Develop syntax

The markdown syntax in this section is non-standard and specific to Touch Develop.

Inline code

Use this syntax: basic => show number

To show code like this: basic-> show number

(-> is replaced with ->)

HTML entities

You can use HTML entities like &, <, or {. You can also use & verbatim if it cannot be confused with HTML entity.

Pictures

You can include pictures in a script by adding an art resource to your script. All pictures must first be uploaded to the Touch Develop cloud before they can be used in a script. Here's how:

1. Click script, + add new, and then click picture resource.

2. You can upload a new picture or search existing pictures.

3. Give it a name, let's say you call it alien.

4. In your script, use (picture ...) with the picture name (in this case, alien) and an optional caption: WARN: missing picture: ... WARN: unknown picture: ...

• ![](/static/mb/image-0.png)

By default, pictures are 12x12. You can specify a different size as in ![](/static/mb/image-0.png), up to 30x20.

To insert a picture inline with text , use: (picture ...) without any size information. For example: ![](/static/mb/image-0.png) WARN: missing picture: ... WARN: unknown picture: ...

You can skip adding an art resource, and instead use the publication ID of a picture directly.

Declarations

Any named declaration from a script can be rendered in a script using {decl:name}. For example, you can render global variables, functions, etc... WARN: no such decl: name

• `

var v: number = 0

wherev` is a global variable in the script:

var v: number = 0

Code snippets

Any code that is not a comment is treated as a snippet.

You can use {highlight} comment to start highlighting statements in the snippet. Use {/highlight} to stop. The comment needs to have {highlight} or {/highlight} and nothing else. MACRO: highlightMACRO: /highlightMACRO: highlightMACRO: /highlight

If you want to render some comments inside the snippets as comments (and not regular text), then surround the snippet with {code} ... {/code}, for example: MACRO: codeMACRO: /code

let theAnswer = 42 // ***
// and now show the answer:
basic.showNumber(theAnswer, 150)

Note that comments inside block structures are always rendered as regular comments, not text. For example:

if (false) {
    // This code is never executed.
}

Boxes and frames

You can use ### ~<type> and ### ~ (each on separate comment line) to enclose a block of text in a coloured box. For example:

~hint

This is how ### ~hint looks like. Some helpful information goes here.

~

The following box types are supported:

• hint, exercise, example - self-explanatory
• nointernet - block with heading "no internet?" for giving instructions for offline operations
• screen - does not show in print
• print - does not show when not printing
• portrait - shows (with no frame or heading) when device is held in portrait orientation; in print it shows with heading "device in portrait" and a frame
• landscape - likewise

Special tutorial features

You'll use markdown syntax when creating Touch Develop tutorials. See create a tutorial for more info.

~hide

Embedding videos

• any video: {video:<screenshot url>:<mp4 url>} where <screenshot url> is a screenshot of the video, and <mp4 url> is the video url that plays MACRO: video If you want to include documents, slides, and videos from other sites, just use regular http://... link.

~