The Jupyter Notebook Formatting Guide
Jupyter notebooks are quite powerful, it serves as a great tool to combine code that can be compiled as well as textual information explaining what the code does in a visually appealing manner.
As a newbie in the Python coding world, I had to struggle understanding the basic formatting and file embedding options. This is a small effort to help new users ace through and ensure they build a Jupyter Notebook worth sharing with anyone.
First things first, the way you can write down text (non-code) content is to select the cell in a Jupyter Notebook and head over to the dropdown box to select “Markdown”.
Download link to a sample .ipynb file implementing all the below formatting techniques.
01. Bold text:
They way you can write bold text is by inserting the text to be written in bold between a pair of double underscores.
Example: __This text to appear in bold__ will be formatted to This text will appear in bold when you run the markdown cell.
02. Italics text:
Marking certain text to Italics is quite similar to what we do to mark text in bold. We have to insert the text to marked in Italics in between a pair a single underscore.
Example: _This text to appear in Italics_ will be formatted to This text to appear in Italics when you run the markdown cell.
03. Line break:
You often end up having to use a line break while writing text, there isn’t really a need to start a new paragraph by inserting two lines gap. You can use a simple <br> tag to insert a line break.
04. Headings:
Headings can be used in 5 different font size, the largest ideally used for titles and the other 4 sizes for headings as and when needed. Headings can be initiated using # followed by space and then the text of the heading. This prints the largest sized heading. You have to keep adding # to make the heading smaller.
Example: # Title prints the largest size heading. ## Heading 1 prints the next smallest heading. The smallest heading would be ##### Heading 4.
05. Colors:
Highlighting some text in a different colour helps put through message that needs special attention. It’s quite simple to achieve this using <font color=pink>The text to be show in pink</font>.
06. Horizontal separator:
If you want to insert a horizontal line that acts as a separator spanning across the width of the markdown cell all you have to do is type three asterisks without spaces in a new line ***.
07. Numbered list and sub-lists:
A numbered list can be generated by typing in a number, followed by a dot and a space
Example: 1. some text
Follow the same pattern for the items following in the numbered list. For sub-lists, a tab space followed by the same format above will generate sub lists with a different label schema automatically. The same technique can be followed for more deeper sublists.
08. Text indentation:
If you would like to display some code or text in an indented block, all you have to do is to start the line with a > followed by a space and then the text. The text is indented and has a gray horizontal line to the left until the next carriage return is detected.
Example: > this is indented text
09. Monospace font:
Monospace font is some text highlighted in a light gray background. Typically used to indicate file paths, user entered messages, file names etc,.
Example: `this is monospace font`
10. Mathematical symbols:
Mathematical symbols can be shown between two $ symbols.
Example: $x = x + y$
11. Internal links:
Internal links can be used to create a link that helps you jump to a certain location on a page. A classic use case would be implementation of an index listof headings. Once a user clicks on a heading in the index list it takes the user directly to the part of the .ipynb file where that heading exists.
Internal links has two components. The source and the destination
Source: This has to be implemented in the location where you would like to get the clickable link. The format for this is [text to appear as link](#linkhandle).
Destination: this has to be implemented in the location where you would like to take the user once the user clicks on the source link. The format followed for this is <a id="linkhandle"></a>. This can be followed by whatever content one wants, be it text or images.
12. External links:
External links follow a format very similar to what we have used for source of internal links. The text to be displayed as link should be inserted between square brackets [click me] and it should be followed by a hyperlink between round brackets (http://google.com).
Example: [click me](http://google.com)
13. Embedding webpage:
If you would like to refer to a particular webpage content in your .ipynb file, it’s quite easy to do so in Jupyter Notebooks. Just use the code below and replace the URL http://raghupro.com as given in the example below with whatever URL you would like to. The other important but optional parameters are setting width and height. The webpage embedded after execution will be a live page that can be accessed by the user.
Example: from IPython.display import IFrame
IFrame('http://raghupro.com', width = 800, height = 450)
Caution note: this above code has to be implemented in a code cell as opposed to markdown cells for all the previous formatting techniques.
14. Embedding PDF document:
Just as easy it was to embed a webpage, it’s equally easy to embed a PDF file into your Jupyter Notebook. Follow the exact code format as with embedding a webpage but replace the URL with a link to a PDF file.
Example: from IPython.display import IFrame
IFrame('https://www.w3.ord/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf', width = 800, height = 450)
Caution note: this above code has to be implemented in a code cell as opposed to markdown cells for all the previous formatting techniques.
15. Embedding YouTube video:
Embedding a youtube video might be a bit tricky. The only part you have to be cautious about is to not paste the entire youtube video URL. The typical format of a youtube video URL is http://youtube.com/watch?v=RBSGK1AvoiM. Here, the part after v= is the unique ID of the video. You have to only copy that part after v= which is the unique ID, RBSGK1AvoiM,and replace it in the example code given below.
Example: from IPython.display import YouTubeVideo
YouTubeVideo('RBSGK1AvoiM', width = 800, height = 500)
Caution note: this above code has to be implemented in a code cell as opposed to markdown cells for all the previous formatting techniques.
16. Notebook themes:
If you feel the look of your Jupyter Notebook is a tad bit boring, you can make it look more exciting by applying themes. First, you have to install the themes executing a simple command in a code cell
!pip install jupyterthemes
After executing the above command, it will show few lines of code in the output below which might take a few seconds depending on your internet connectivity as it has to download the modules from a remote server. Once installed, you can use the following command to see a list of all themes available to choose
!jt -l
This will show a list of all available themes. You can apply any theme using the following command
!jt -t <name of theme>
Example: !jt -t chesterish
Note: you have to completely shutdown and restart jupyter notebook every time you apply a new theme
Voila! This will apply the theme. If for some reason you would like to revert back to the original stock theme, just execute the command below.
!jt -r
Download link to a sample .ipynb file implementing all the above formatting techniques.
