Custom Styling#
Although content contributed to The Turing Way should be written in Markdown where possible, sometimes, HTML
syntax may be necessary to format your contribution the way you desire.
Already, Jupyter Book converts Markdown syntax to HTML
, making it possible to have a web version of The Turing Way book.
As a result, writing your own custom HTML
may introduce some variation in the way your new content appears online compared to the rest of the book.
To minimise this disparity, The Turing Way maintains book-wide stylesheets that control the look and feel of the book’s content.
When including HTML
in your contributions, please refer to these stylesheets and add the relevant classes and IDs defined there to your HTML
elements.
This ensures that your new content fits the overall style of The Turing Way book.
In this subchapter, we provide an explanation of how to leverage the book’s stylesheets to style your contributions in sample use-cases. If you want to improve the style of the book, this subchapter also provides a brief overview of how to do so.
Using the Stylesheets#
Videos#
While it is possible to embed images and GIFs in your content using Markdown syntax, it is currently only possible to embed videos with HTML
.
More so, we do not recommend adding videos directly to The Turing Way’s Github repository as video files are usually large and will make the book load much slower, especially for readers with slow internet connections.
To add a video to your contribution, first upload it to The Turing Way’s Youtube channel, then copy/paste the HTML
code that is generated when you:
Click on the
Share
option underneath the video,And then click on the
Embed
option from the range of options that appear.
The HTML
code you copy will be an iframe
element.
For example:
<iframe width="560" height="315" src="https://www.youtube.com/embed/MdOS6tPq8fc" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
By default, iframes
are not responsive, meaning that the video you just embedded will be inaccessible to readers on mobile devices.
To fix this, The Turing Way’s stylesheets define classes and styling that allow iframes
to resize and fit the screen the book is read from.
To leverage this custom styling, wrap the iframe
in div
tags and give the div
element a video-container
class. For example:
<div class="video-container">
<iframe width="560" height="315" src="https://www.youtube.com/embed/MdOS6tPq8fc" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
</div>
The code above then renders as follows:
Improving The Turing Way’s Styling#
Jupyter Book works by converting Markdown syntax to HTML
.
Therefore, to improve the overall styling of the book, CSS
rules should target the HTML
elements that Jupyter Book generates.
Before writing any CSS, inspect the book’s HTML source code first. This gives you an idea of what elements to target, and may help you figure out how to structure your CSS rules.
All web browsers allow you to view the source code of websites easily.
On computers running the Windows OS or Linux, this is done using CTRL + U
.
For computers running Mac OS, this is done using Option + Command + U
.
Once you have determined the element(s) you want to modify, write your CSS in The Turing Way’s stylesheet file.
If, for example, you wanted to change the font-family
of the paragraph text across the entire The Turing Way book, then you could add the following CSS rule to the stylesheets which target
all elements with a <p>
tag:
p {
font-family: georgia, garamond, serif;
}
If you think that the styling introduced in The Turing way can be useful for other Jupyter Book users, please consider making an upstream contribution to the project by creating a new GitHub issue and starting a discussion with their maintainers: executablebooks/jupyter-book#issues.