Task Description

The task description can be written in HTML or Markdown (CommonMark spec) and allows formatted code to be rendered, as well as images and other media to be embedded. Every task must have either a text.html or a text.md file in its text directory containing the description.

Embedding Media

There are two approaches to embedding assets:

1. External: Assets are hosted on an external web server and embedded via URLs.
2. Internal: Assets are bundled with the task, stored in the text directory, and referenced in the description using relative paths.

We recommend embedding assets internally, as the asset is part of the task and should be versioned together with it. Keeping assets along with the task, rather than on an external server, also ensures that they remain accessible over time.

Example: Internal

The organization of files is up to you, as long as the files live somewhere under the text directory.

- 15Appointment
    - text
        - text.html (or text.md)
        - images
            - example.png
    - ...

HTML

text.html

<img alt="Star example" src="images/example.png"/>

Markdown

text.md

![Star example](images/example.png)

Migration Utility

To migrate older tasks that use external media, use the getImages.jshell script:

1. Start JShell in the directory that holds your tasks (one directory per task): jshell
2. Load the script: /open ~/getImages.jshell
3. Run getImages()

The script walks every visible directory, reads text/text.html, downloads the referenced assets into text/images, and rewrites the absolute URLs to relative paths.

Syntax Highlighting and LaTeX

Subato supports syntax highlighting for a wide range of formal languages, each identified by a language alias. A complete list of supported languages and their aliases is available in the Prism.js documentation. For example, Python can be specified using the aliases python or py. Subato also supports rendering simple LaTeX expressions (such as $f(x) = x^2$) in both HTML and Markdown files.

HTML

Define a pre element with the class language-<alias>:

text.html

<pre class="language-python"><code># Given: a real number x
    int algo(x):
       if x &lt;= 1:
           return 0
       else:
           return 1 + algo(x/3)</code></pre>

Markdown

Define a fenced code block with the alias right after the backticks:

text.md

```python
int algo(x):
   if x < 1:
       return 0
   else:
       return 1 + algo(x/3)
```