Writing Guide

The majority of our text content is written in Markdown, and we also developed a program called Verto to allow you to include HTML elements like images and videos with simple text tags.

For example, the following text:

# Scratch Programming Challenge

Try using the following blocks to create a program to display numbers 1, 2,
4, 8 and 16 on the screen, one at a time.


```scratch
when flag clicked

say [Hello] for [2] secs
```

Your program should look like the following:

{iframe link="http://scratch.mit.edu/projects/embed/148423714/?autostart=false"}

{panel type="note}
# Tips

- Make sure all your blocks are “snapped” together in a line like a
  jigsaw puzzle.

{panel end}

{button-link link="challenge/scratch-solution.html" text="Scratch Solution"}

will display as the following on the website:

An image showing the above Markdown syntax rendered as HTML

Note

If you already know Markdown syntax, please remember the following project preferences (for consistency and readability):

  • Use asterisks (*) for emphasis, instead of underscores.

  • Use hyphens (-) for unordered lists.

  • No HTML within text files, we use Verto text tags to add iframes, images, videos, etc.

Below is a basic guide to syntax for Markdown and Verto text tags. When viewing Verto documentation for a tag, the top of the page will detail how to use the tag in a basic example. Some text tags also have required and/or optional tag parameters for further configuration.

Text Syntax

Blockquotes

> Blockquotes are very handy to emulate reply or output text.
> This line is part of the same quote.

Quote break.

> Oh, you can *put* **Markdown** into a blockquote.

Boxed Text (Verto feature)

Click here to read the documentation on how to box text.

Code

You are able to include code snippets, either in a line of text or as a new block.

To include inline code, add a backtick to either side of the code. For example: `print(“Hi”)` will display as print("Hi"). You cannot set the language syntax highlighting for inline code.

To create a code block, use a line of three backticks before and after the code. You also can add syntax highlighting by specifying the language after the first set of backticks (list of language codes).

```python3
def find_high_score(scores):
    if len(scores) == 0:
        print("No high score, table is empty")
        return -1
    else:
        highest_so_far = scores[0]
        for score in scores[1:]:
            if score > highest_so_far:
                highest_so_far = score
        return highest_so_far
```

def find_high_score(scores):
    if len(scores) == 0:
        print("No high score, table is empty")
        return -1
    else:
        highest_so_far = scores[0]
        for score in scores[1:]:
            if score > highest_so_far:
                highest_so_far = score
        return highest_so_far

Comment (Verto feature)

Click here to read the documentation on how to add a comment.

Conditional (Verto feature)

Click here to read the documentation on how to define a conditional.

Embed iframe (Verto feature)

Click here to read the documentation on how to embed with an iframe.

Emphasis

Emphasis, aka italics, with *asterisks*.

Strong emphasis, aka bold, with **asterisks**.

Emphasis, aka italics, with asterisks.

Strong emphasis, aka bold, with asterisks.

Note

We do not use underscores for emphasis to maintain consistency and readability.

Heading (Verto feature)

Click here to read the documentation on how to create a heading.

Image (Verto feature)

Click here to read the documentation on how to include an image.

Interactive (Verto feature)

Click here to read the documentation on how to include an interactive.

Line Breaks

Here are some things to try out:

Here's a line for us to start with.

This line is separated from the one above by two newlines, so it will be a
*separate paragraph*.

This line is also a separate paragraph, but...
This line is only separated by a single newline, so it's a separate line
in the *same paragraph*.

Lists

Lists can be created by starting each line with a - for unordered lists or 1. for ordered lists. The list needs to be followed by a blank line, however it doesn’t require a blank line before unless the preceding text is a heading (a blank line is then required). If you are having issues with a list not rendering correctly, try adding a blank line before the list if there is none, otherwise submit a bug report if you are still having rendering issues.

Unordered list:
- Item 1
- Item 2
- Item 3

Ordered list:
1. Item 1
2. Item 2
3. Item 3

Unordered list:

  • Item 1

  • Item 2

  • Item 3

Ordered list:

  1. Item 1

  2. Item 2

  3. Item 3

Nested lists can be created by indenting each level by 2 spaces.

1. Item 1
  1. A corollary to the above item, indented by 2 spaces.
  2. Yet another point to consider.
2. Item 2
  * A corollary that does not need to be ordered.
    * This is indented four spaces, because it's two for each level.
    * You might want to consider making a new list by now.
3. Item 3

  1. Item 1

  1. A corollary to the above item, indented by 2 spaces.

  2. Yet another point to consider.

  1. Item 2

  • A corollary that does not need to be ordered.

    • This is indented four spaces, because it’s two for each level.

    • You might want to consider making a new list by now.

  1. Item 3

Math

To include math (either inline or as a block) use the following syntax while using LaTeX syntax.

This is inline math: ``\( 2 + 2 = 4 \)``

This is block math:

``\[ \begin{bmatrix} s & 0 \\ 0 & s \\ \end{bmatrix} \]``

Math equations are rendered in MathJax using the LaTeX syntax.

Panel (Verto feature)

Click here to read the documentation on how to create a panel.

Supported panel types

These are the panel types that have built in styling for CS Unplugged. Other panel types are supported, but will not have any special styling. Have a play around with them to see how they look!

  • ct-algorithm

  • ct-abstraction

  • ct-decomposition

  • ct-pattern

  • ct-logic

  • ct-evaluation

  • video

Scratch (Verto feature)

Click here to read the documentation on how to include an image of Scratch block.

Table of Contents (Verto feature)

Click here to read the documentation on how to include a table of contents.

Tables

Tables can be created using the following syntax:

Colons can be used to align columns.

| Tables        | Are           | Cool  |
| ------------- |:-------------:| -----:|
| col 3 is      | right-aligned | $1600 |
| col 2 is      | centered      |   $12 |
| zebra stripes | are neat      |    $1 |
Tables Are Cool
col 3 is right-aligned $1600
col 2 is centered $12
zebra stripes are neat $1

The outer pipes (|) are optional, and you don’t need to make the raw Markdown line up prettily, but there must be at least 3 dashes separating each header cell. You can also use inline Markdown.

Markdown | Less | Pretty
--- | --- | ---
*Still* | `renders` | **nicely**
1 | 2 | 3
Markdown Less Pretty
Still renders nicely
1 2 3

Video (Verto feature)

Click here to read the documentation on how to include a video.