Skip to article frontmatterSkip to article content

We encourage you to use images in The Turing Way book chapters to help readers understand the concepts discussed in the chapter better.

This section of the style guide will explain how to use Markedly Structured Text (MyST) format to add them to the book with appropriate alt text and captions. This is sometimes tricky, refer to the Advanced features and “gotchas” section for troubleshooting.

We are very passionate about ensuring that the creators of the original image files (including you!) are acknowledged appropriately. Please do not use images that are not licenced for reuse.

In this sub-chapter we have used the term figure to refer to an illustration that conveys information in the context of The Turing Way chapters. The term image is used to refer to the file object itself.

Open licence

Please ensure that you attribute the image files fairly and avoid files that are either restricted from reuse or lack reproduction permissions.

The following recommendations will help you to check that you’re using the images according to their licence permissions:

In general, make sure to always cite the image properly as directed by the image owners. “Image from the internet” is not enough.

Image location, type, size and file name

Every image file used in this book should be located in the directory book/website/figures of our GitHub Repository. If you use a new image file, please add the file in the figures directory by either uploading via GitHub, or adding locally and pushing the change online when using git.

Please upload .jpg, .png, or .svg files that are under 1MB to allow them to load faster in the online book. If your file is larger than 1MB, please use a local image editing tool, or online tool like IMG2GO to compress your file.

To name your image file, please use all-lowercase and separate words with hyphens (-).

Alternative text

Alternative text or alt text are used for describing the appearance and function of an image on an HTML page for users who cannot see it. Alt text is often used by visually impaired people who use assistive technology such as screen readers. Adding alt texts to figures is one of the first principles of web accessibility as it enables the screen reader software to read an alt text to its users helping them understand/explain the content.

If an image link breaks, alt texts are still functional and read as intended by the assistive technology.

For more, visit the Alt text section

Please note that a height of 500px works very well with The Turing Way book, but this is only a suggestion.

Caption

Captions appear below the figure. They should be short and concise and include a reference to the source where they are taken from. In particular it is important to describe the licence under which the image is re-used.

For example, a caption might say:

Making your first pull request on GitHub. The Turing Way project illustration by Scriberia. Used under a CC-BY 4.0 licence. DOI: The Turing Way Community & Scriberia (2024).

The syntax for this image is as follows, and the way it appears in the book is below the code snippet.

```{figure} ../../figures/first-pull-request.*
---
height: 400px
name: first-pull-request
alt: >
  Cartoon-like sketch of two persons sitting across from each other working on their laptops.
  A straight arrow on the top indicates the main branch of the repository that they are working on,
  a pull request is shown by a branch coming out of the main arrow labelled as Clone,
  followed by a Pull Request with the changes that the first person made in the branch,
  and the final step labelled as Approved that indicates approval of the changes by the second person.
  This arrow then merges back to the main arrow/repository.
---
Making your first pull request on GitHub.
_The Turing Way_ project illustration by Scriberia. Used under a CC-BY 4.0 licence. DOI: [10.5281/zenodo.3332807](https://doi.org/10.5281/zenodo.3332807).
```
Cartoon-like sketch of two persons sitting across from each other working on their laptops. A straight arrow on the top indicates the main branch of the repository that they are working on, a pull request is shown by a branch coming out of the main arrow labelled as Clone, followed by a Pull Request with the changes that the first person made in the branch, and the final step labelled as Approved that indicates approval of the changes by the second person. This arrow then merges back to the main arrow/repository.

Figure 1:Making your first pull request on GitHub. The Turing Way project illustration by Scriberia. Used under a CC-BY 4.0 licence. DOI: The Turing Way Community & Scriberia (2024).

Please make sure that the link to the source is the digital object identifier not the Zenodo record. Also ensure that you have created a link to the source using markdown link formatting: [text](url).

Figure information with the block delimited by --- makes use of yaml syntax. Some characters (such as ‘:’) have special meaning in YAML and using they may create unexpected results. This comes up quite often in longer blocks of text, such as the alt text tag. Using the syntax demonstrated above, alt: >, means you can have multi-line outputs and only need to escape | and > to get those literal characters in the final output. You escape a character by prepending it with a backslash for example, \| and \>. for more on multi-line strings in yaml see: Demystifying YAML Multiline Strings: An In-Depth Guide.

Cross-Referencing Figures in Other Chapters

After a figure is added in a chapter, it can be referred in other files using the {ref} role like:

{ref}`file-collection`

Advanced features and “gotchas”

For more advanced parameters, please visit the Jupyter Book Documentation. That page includes information on how to scale and align the figures, and how to add the figures or their captions to the margins of the book.

We’ve noticed a couple of “gotchas” from contributors to The Turing Way and we’ll try to keep this section of the guide up to date for anyone else learning the MyST syntax for figures.

References
  1. The Turing Way Community, & Scriberia. (2024). Illustrations from The Turing Way: Shared under CC-BY 4.0 for reuse. Zenodo. 10.5281/ZENODO.3332807