Touch Develop retirement postponed until June 22, 2019. Sign-in and access to cloud assets to be removed on May 23, 2018.Learn More..


markdown

Markdown is a popular syntax among developers to describe documents. Comments supports a large subset of the markdown syntax but adds a couple new features specific to the environment.

basic syntax

headings

  • # heading 1
  • ## heading 2
  • ### heading 3

heading 1

heading 2

heading 3

lists

* this is a bullet
* this is a another bullet
  • this is a bullet
  • this is a another bullet

bold, italic

  • *italic* => italic
  • **bold** => bold
You can also use _ instead of *, but it's not recommended.

links

specialized syntax

This part of the syntax is non-standard and specific to authoring TouchDevelop topics.

inline code

  • TouchDevelop code: `web->csv(...)` => web→csv(...); we add links and replace -> with etc.
  • non-TouchDevelop code: ``#docs`` => #docs; no links, no replacement
  • TouchDevelop editor UI elements: `[publish]` button => publish button
Tip: Use ` to insert literal backtick.

HTML entities

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

more links

  • topic link [] (/docs/events) => events
  • script links [facebook game starter] (/script:vtbo) => facebook game starter
  • links inside the document [Section 1] (#sect1) -- this is not working yet, but the syntax is reserved
  • links inside the app [go to hub](#hub:dummy) => go to hub -- these need to have colon (:) in them, otherwise they are treated as links inside the document
  • any publication id, script, user, comment, ... {pub:bqsl}
  • http, https, ftp, and mailto links work as expected
Other links are not allowed.

meta-information

  • {meta:hidden} will hide the current topic in the list on the left hand side (unless dbg).
  • {priority:123} ranks the topic priority. Only topics with priority defined will show up in the search list by default. Topics are sorted in increasing number of priority.
  • {template:abcd} - when the user taps follow tutorial button and is not yet in the editor, than the script with id abcd will be used as the template for following the tutorial
  • {templatename:ADJ monsters} - name to use when follow tutorial is tapped; ADJ is replaced with an adjective like "awesome" or "phenomenal"

pictures

Pictures can be inserted using the following steps:
  • add art resource to your script; you can either upload a new picture or search existing ones; give it a name, let's say you call it alien
  • insert a {pic:...} macro with the picture art variable name
  • {pic:alien:This is a **caption**.}
This is a **caption**.
By default, pictures 12x12 em. You can specify different size as in {pic:alien:5x3:Some caption}, up to 30x20.
Picture 5 by 3
  • you can also includes pictures in text, picture, using the {pici:alien} macro. No size setting is available for this particular macro.
Limitations:
  • The art name must be a combination of letters and spaces
  • The art must have been uploaded to the TouchDevelop cloud. You are not allowed to use art that refers to an arbitrary URL.
You can also skip adding the art resource, and instead use publication ID of a picture directly.

requirements

  • {cap:accelerometer,gyroscope} specifies that the topic requires Accelerometer and Gyroscope support.
This code might not work on your current device: missing Gyroscope capabilities.

embedding videos

  • YouTube videos: {youtube:abc} where abc is the YouTube video id
  • Channel9 videos: {channel9:<mp4 url>} where <mp4 url> is the URL of the MP4 movie.
  • any videos: {video:<screenshot url>:<mp4 url>} where <screenshot url> points to an image screenshot of the video, <mp4 url> points to the video url that will be loaded when playing.
If you want to include documents, slides, and videos from other sites, just use regular http://... link.

embedding localized videos with captions

A more advanced scenario is to display different video for various locales and close caption tracks. This can be specified by storing this information a string art resource and inserting the string art resource name in the {video:<resource name>} macro.
The example belows shows how the format of the JSON payload:
art my video : String
with data:
{ "poster": "url to the poster image", "sources": [{ "srclang":"en", "src":"url to the English video", "type":"video/mp4" },{ "srclang":"fr", "src":"url to the French video", "type":"video/mp4", "poster": "url to the French poster" }], "tracks": [{ "srclang":"en", "src":"url to the WebTT English closed caption file", "label": "English" }] ...

declarations

Any named declaration from the script can be rendered using {decl:name}. For example, you can render global variables, events, records, etc...
  • {decl:v} where v is a variable under data in this script.
data v : Number

imports

All javascript imports using app→import can be listed using {imports}.

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.
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:
var the answer := 42
And now print the answer:
the answer → post to wall
Note that comments inside block structures are always rendered as regular comments, not text. For example:
if false then
This code is never executed.

variables

The {var:...} will expand well-known variable names to the values. The following variables are supported:
  • userid: 'unknown macro 'var' ', the user id of the current user.

boxes/frames

You can use {box:<type>} and {/box} (each on separate comment line) to enclose a block of text in a special colored box. For example:
hint
This is how {box: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

localization

It is possible to specify alternate scripts for different locales using {translations:...}. In such case, TouchDevelop will use the description of the steps in the specified script instead. When using this feature, ensure that different localized scripts have matching steps. The example below shows how to specify French and Spanish.
{translations:locales}
where locales is a string resource contain a line for each localized script with a locale=script id pair.
art locales : String
with data:
fr=<French script id> es=<Spanish script id> ...
TouchDevelop will automatically pick up the latest update of the referenced script. However, that translation will be cached. To invalidate any cache issues, re-publish the main script.

specialized tutorial features

API tables

{api:type name} will list the properties of a given type, e.g., {api:bazaar} gives:
Additionally, {api:type:prop1,prop2} will list help for type→prop1 and type→prop2. {api:type→prop1,type→prop2} has the same effect.