The current authoring system is based on importing Jupyter notebooks that have some extra stuff embedded in them to unlock the full power of the codex format. Essentially, you'll author a normal notebook and then add special directives that instruct Pathbird to do something special (e.g., insert a multiple choice or autograded quiz).
This document is meant to be a reference rather than a tutorial. Check out a demo notebook (My first codex) which gives examples of how to use most of the directives. When authoring your own content, you might want to keep this document open so that you can refer to the exact syntax. If something is missing, please reach out to Travis at travis@pathbird.com.
MyST is just Markdown and some stuff. All markdown syntax should work. The additional syntax is meant to "gracefully" degrade to readable markdown.
The main addition is Directives which are described below.
<aside> 👉 In most Markdown renderers, content that is only separated by a single newline is rendered as part of the same paragraph. As a stylistic choice (so that it's prettier in a markdown editor like Jupyter), it might make sense to add an additional newline to separate directive fences (so that everything doesn't run together as a single line).
</aside>
Pathbird uses KaTeX rather than MathJax (which is what Jupyter notebook & Jupyter lab both use). KaTeX is stricter than MathJax, but it is much more consistent and performant. Watch out for the following pitfalls.
Mynerva doesn't support \\begin{align} environments (yet!), you'll need to use an aligned environment inside math mode (i.e., the $$'s are mandatory for now):
$$
\\begin{aligned}
a &= 1 + 2 + 3 \\\\
&= 3 + 3 \\\\
&= 6
\\end{aligned}
$$
Mynerva doesn't support \\label and \\ref yet (there are plans to add some similar functionality in the future!)
Most other TeX functions are supported. See the KaTeX Support Table for more information.
Directives can be defined with ::: (three+ colons) or ````` (3+ backticks). These sequences are called fences. The colon syntax should be used for directives that contain markdown text while the backtick syntax should be used for directives that contain code.
Directives can be nested, but the outer directive must have a longer fence than all inner directives (for example, :::{prompt} can appear in ::::{multiplechoice} because the former has three colons and the latter has four).