Tips for customising course appearance

[callummole]

We can use MyST (Markedly Structured Text) in jupyter-books to help customise the appearance. MyST builds on common markdown to give more functionality for things like adding notes to margins, hiding code and figures, adding a sidebar etc.

This issue is for sharing knowledge on tips that are useful for the course.

MyST Cheatsheet

These are easy to use and will be great for highlighting important take-homes or for including additional but tangential advice in the margins.

[callummole]

Adding a note in the margin is quite effective.

You can also just use below if you don't need a title.

````{margin}
```{admonition} title
content

You can also just use below if you don't need a title.

````{margin}
```{note}

[callummole]

You can also add code to the margin by adding metadata to your code block.

In notebook browser go View->Tags->Edit Metadata, then add a list of tags, like the following:

{
  "tags": [
    "margin",
    "hide-input",
    "hide-output"
  ]
}

The tags are found in the cheatsheet in the root comment.

You only need the margin tag to put the code in the margin. I added the hide tags here because the code was included after a margin note, and looked a bit busy. But usefully it is still clickable to expand if someone was interested.

Unfortunately it doesn't seem possible to add code to a sidebar (which would have been a neater way of showing a note and code). A sidebar is a slightly bigger margin but with a vertically dividing line from the main text.

[callummole]

You can do expandable text with a title by using <detail> and <summary>, like so:

![](https://i.imgur.com/4OUGwbR.png)
<font size="1">[Source](https://badvisualisations.tumblr.com/post/184827953341/this-is-not-all-you-need-to-click-through-to-this)</font>
<details>
    <summary>Example 10 notes</summary>
The labels on this plot are really ugly and it detracts from the message. The y axis could be represented on a scale of millions (i.e. from 0 to $500), and there is no need to note all the data points. If one wants to write out the data, use a table!
</details>

Source

Example 10 notes

The labels on this plot are really ugly and it detracts from the message. The y axis could be represented on a scale of millions (i.e. from 0 to $500), and there is no need to note all the data points. If one wants to write out the data, use a table!