Writing Guide

The Computer Science Field Guide is developed in English and then translated into other languages. You can find more information about this on the Translations page.

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:

{panel type="teacher-note"}

# This section contains extension material

This section is an extension aimed at keen students.
Primary school kids have been able to understand many of these ideas, although it really depends on how engaged the students are with the material.

{panel end}

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.

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.

Embedded 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.
However, *this* line is only separated by a single newline in the markdown file.
These are new sentences that will appear **on the same line** as each previous one.

When writing markdown, new sentences should be started on a new line for clarity.
An exception is for really small sentences like this:
Is it one? two? three?

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. However, this line is only separated by a single newline in the markdown file. These are new sentences that will appear on the same line as each previous one.

When writing markdown, new sentences should be started on a new line for clarity. An exception is for really small sentences like this: Is it one? two? three?

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 4 spaces.

1. Item 1
  1. A corollary to the above item, indented by 4 spaces.
  2. Yet another point to consider.
2. Item 2
  * A corollary that does not need to be ordered.
    * This is indented eight spaces, because it's four 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 4 spaces.

  2. Yet another point to consider.

  1. Item 2

  • A corollary that does not need to be ordered.

    • This is indented eight spaces, because it’s four 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.

An image showing the above Markdown syntax rendered as HTML

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 CSFG. Other panel types can be used, but they will not have any special styling. Have a play around with them to see how they look!

  • additional-information

  • caution

  • curiosity

  • challenge

  • exercise

  • jargon-buster

  • project

  • spoiler

  • teacher-note

    • NOTE: Teacher Notes will only be visible if Teacher Mode is enabled

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.

Writing structure

Chapters always contain the following:

  • An introduction page, which introduces the reader to the chapter.

  • Several chapter sections, which each cover a key sub topic of the main chapter.

  • A The whole story! page, which should mention some other related concepts not covered by the chapter.

  • A Further reading page, which contains links and/or book references where students can investigate the topic further.