Advanced formatting using MyST Markdown
Contents
Advanced formatting using MyST Markdown¶
Hopefully you will be happy with the webpages you have produced. To my mind, Jupyter Book makes one of the cleanest and most easily-navigable sets of webpages for lecture material from the various options I have seen for making accessible mathematics material (RMarkdown coming a close 2nd).
I mentioned earlier that on top of the standard Markdown formatting options, using Jupyter Book allows us to do a few extra bits and pieces, which I’ll cover here.
Admonitions¶
These produce special textbox-like blocks that can be good for highlighting particular pieces of material. We can create these by writing,
```{admonition} Choose your own title
I have something interesting to say at this point (unusually).
```
which will appear as,
Choose your own title
I have something interesting to say at this point (unusually).
There are a number of other standard admonitions available, including the following:
Note
The ‘Note’ title is inserted automatically, so I can just get on and write something.
Tip
My tip is that you read more about the admonitions on the Jupyter Book MyST cheatsheet webpages.
There are many other standard forms too. It is worth noting that when you include these in your Jupyer Notebook they will initially not format into these nice-looking boxes but will instead look just like some weird code output. That is because Jupyter Notebook is just using Markdown, not MyST Markdown. It is only when you compile the Jupyter Book that it will come out looking like this.
There are a couple of more advanced blocks you can use as well. For example, one useful tool when designing learning materials is that you set an exercise, then have a worked solution that is initially hidden and only revealed when the student clicks on it:
Click here to reveal what’s inside the box
I can put my solution in here. Just to prove the point, this can include mathematical working, such as,
You can also use this in combination with one of the standard admonitions.
Theorems, proofs, etc.¶
I briefly touched on how we might include some basic Markdown formatting of theorems, etc in an earlier section. Using Jupyter Book we have some more advanced options available to us. Given what we’ve just seen, you can probably see that we could make use of the admonitions we have just seen. However, we can in fact go even further, but it does involve a little bit of preparatory work.
In partcular, there is an extension we can install called sphinx-proof that will allow us to format some of these specialist styles. First it needs installing by typing int he command line,
pip install sphinx-proof
Then you need to open the _config file and add,
sphinx:
extra_extensions:
- sphinx_proof
We can then include a variety of different formats that are fairly standard for mathematical learning resources. As an example, if we type,
````{prf:theorem} Whatever can go wrong will go wrong
:label: my-theorem
There is a non-zero probability that I have made a typo somewhere in ths theorem.
````
we get,
Theorem 1 (Whatever can go wrong will go wrong)
There is a non-zero probability that I have made a typo somewhere in ths theorem.
which looks like a nice theorem. A few further examples are below,
Proof. Theorem 1 can be proven by carefully reading the theorem.
Example 2
There are many more examples in the sphinx-proof guide, linked to from the relevant Jupyter Book webpages.
Other options¶
There are many more things we can do with MyST Markdown that I won’t get into the details of here. I strongly encourage you to look through the Jupyter Book documentation, but as a taster a few things you can do are:
Include equation numbering in such a way that they can be cross-referenced.
Include images as figures, allowing for captions and cross-referencing.
Create tabs, where users can click to reveal one tab at a time.
Create cards to highlight certain elements (like a simple version of the admonitions above).