Jupyter and Markdown. Making your Notebooks look good | by Alan Jones | Towards Data Science

You can put comments in your Jupyter Notebook code to help the reader to understand what you are up to. But longer commentary is better in text cells separate from the code.
Text cells in Jupyter support the Markdown language and we are going to take a look at the facilities that it offers. Markdown is a set of simple markup codes that are easily transformed into HTML for rendering in a browser. Markdown is nowhere near as sophisticated, or complex, as HTML but is perfectly adequate for documenting a notebook (although can also embed HTML if you need more control over the look or layout).
This article was initially written in Markdown (there is a link to the original at the end of this article) and the first paragraph and the two headings looks like this:
# Jupyter and Markdown## Making your Notebooks look goodWhether you are sharing your Jupyter Notebooks with friends and colleagues or publishing them more widely, they will be better appreciated if they are well layed out and formatted.
Very simple. The # precedes a heading equivalent to <h1> in HTML, two of them means a secondary heading, <h2>. The more # symbols, the smaller the heading.
So the following Markdown code will display a list of headings gradually reducing in size.
# heading 1## heading 2### heading 3#### heading 4##### heading 5###### heading 6
Markdown supports the most common styling such as bold and italic, you can construct lists both numbered and unnumbered. You can embed code within a paragraph or display a complete code block. Hyperlinks are included and you can insert images, too. Tables can be constructed with left and right justified columns with very simple syntax.
Markdown ignores single line breaks, so to separate paragraphs, you need to insert two line breaks.
Below we are going to go through some examples of the Markdown code. For each example I’ll show you the Markdown code and then follow it with the way that it will look after being rendered.
First we’ll take a look at some simple inline markup.
Here is the code and below it is the rendered version:
This is a paragraph that illustrates some of the Markdown features.This is a new paragraph that includes some code: `print(123)` you can see that it is enclosed in single back ticks. Other simple markup is *italic which is enclosed in asterisks* and **bold which is enclosed in double asterisks**.
You can use single or double underscores to make text italic or bold. So, by mixing underscores and stars you can have text that is both italic and
You can also use an _underscore to make things italic_, or two of them for __bold__. This means you can have both _**italic and bold**_ text.
Block quotes are preceded by a chevron.
> To include a block quote you precede it with a `>`
If you want to include a code block use three backticks or ~ characters to enclose the code like this:
~~~pythonfor i in (1,2,3):   print(i)~~~
or this
```pythonfor i in (1,2,3):   print(i)```
and you’ll get a block of code which will probably be colour coded:
Note that the use of the name a programming language is optional and, although it is not part of the Markdown specification, colour coding is included in most renderers.
There are both ordered and unordered lists. The items in an unordered list are preceded by a star, minus or a plus:
+ item- item* item
This looks like
item
item
item
Sublists are just indented with a space:
+ item + item + item+ item
Numbered lists begin with — you guessed it — a number, followed by a dot. And you can mix and match ordered, unordered and sub-lists.
1. item2. item3. item + item + item4. item
Images are referenced by their path or URI. To include an image the line starts with an exclamation mark followed by a pair of square brackets where the alt-text goes then a pair of braces containing image path and a string which will be displayed when you hover over the image.
![alt_text](https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png “Markdown Logo”)
Links look similar to images except the text in the square brackets is the actual link text.
Here is a link to [Google’s](https://www.google.com “Google’s Homepage”) home page.
Which is rendered as:
Here is a link to Google’s home page.
In a table the columns are separated with the pipe character(|) and the header is followed by a row of dashes, then the rest of the data follows row by row, like this:
Col1 |Col2 |Col3-----|-----|----- Data1|Data2|Data3Data1|Data2|Data3Data1|Data2|Data3Data1|Data2|Data3
You can also align columns by placing colons in the header underline. A colon of the right means right aligned, on the left means left aligned and one on each side is centered. Here’s an example:
Left aligned column | Centered column | Right aligned column:-------------------|:---------------:|--------------------:**Bold data**       | *Italic data*   | Normal data
And, as you see, the entries in the table can be made bold or italicised.
The layout of the code does not have to be neat, Markdown will sort it out. This messy version of the table above is rendered exactly the same.
Left aligned column | Centered column | Right aligned column:-|:-:|-:**Bold data**|*Italic data*| Normal data
You can add whatever HTML you want, if Markdown doesn’t do exactly what you want.
Here’s a bit of Markdown text. Can you see the difference between**Markdown bold** and <b>HTML bold</b>?No, you can’t because it’s the same!
Here’s a bit of Markdown text. Can you see the difference between Markdown bold and HTML bold?
No, you can’t because it’s the same!
And to finish off here is a horizontal line. Just type three dashes on a line by itself
---
(There is no horizontal line in the Medium editor but I’m sure you can imagine one!)
That’s plenty enough to make your Jupyter Notebooks into attractive readable documents, I think.
Since Medium doesn’t support all of the stuff that Markdown can do, I’ve relied to a considerable extent on images. But if you would like to see the original version of this notebook you can view it, or download it, here.
And if you would like to be informed about future articles please subscribe to my free Technofile newsletter.