12. MyST-and-Sphinx Way of Doing Things#

There are a lot of features that may come up when designing notes/webpages. If you’ve followed this guide linearly so far, you should have seen notes on margins, highlighted text (also called admonitions) and will see synced tabs, code output and possibly other things too. These are often implemented via directives, which are blocks of explicit markup that often look like this:

```{directive-name}
{additional-config}
content
```
I am a directive too! Click me!

There are also roles, which are in-line directives, great for things like adding math like \(a^2+b^2=c^2\) or abbreviations like KKT that one can hover over. The often look like this:

{role-name}`content`

This distinction may be helpful when googling.

Everything that is not just regular text is probably some directive. Some of these features can be achieved with Markdown or LaTeX as well, but using the correct directive often offers more configurability. If you see something on these pages that you’d like to use, check out its source file.

12.1. Images and Figures#

One can add images the Markdown way (via ![](<link-to-image>))). Sphinx has an {image} directive, where one can specify layout and alignment. An often better alternative is the {figure} directive, which allows for captions and referencing as well.

```{figure} picture.png
:label: example_picture
:align: center

This is the caption.
```

Important

You can’t add a PDF as an image in an HTML file. While there seems to be a mechanism to automatically convert things when needed, I couldn’t get it to work yet. But a reliable way to make images work, if you’d like to use .png in HTML files and .pdf in LaTeX, is to save both file types in the same directory, and give the image path as for example images/myimage.*. The appropriate version should be picked automatically for different types of outputs being built.

12.2. References#

Here is a citation [OGHG13].

And here is a bibliography:

OGHG13

F. Oliveira, V. Gupta, S. Hamacher, and I. E. Grossmann. A lagrangean decomposition approach for oil supply chain investment planning under uncertainty with risk considerations. Computers and Chemical Engineering, 2013. doi:10.1016/j.compchemeng.2012.10.012.

Wil13

H. P. Williams. Model building in mathematical programming. Wiley, Hoboken, N.J, 5th ed edition, 2013. ISBN 9781118443330.

More examples and configuration here.

12.3. Footnotes#

There is no Sphinx way of adding footnotes. You can use the Markdown way:

Text with footnote [^1]. More text.

[^1]: I'm the footnote.

results in:

Text with footnote 1. More text.

In HTML outputs, the footnote is put to the bottom of the page. For more immediate visibility, you may want to use admonition or margin directives instead.

12.4. Further Reading#

1

I’m the footnote.