Jupyter Lab Markdown Cheat Sheet

Learning Objectives

• Explain what the Markdown format is.
• Describe the role of Markdown for documentation of earth data science workflows.
• Use Markdown syntax in Jupyter Notebook to:
  • Create headers and lists
  • Bold and italicize bold text
  • Render images and create hyperlinks to web pages

Using markdown, you can quickly include headers, links, images, bold or italic text, paragraphs, and ordered or unordered lists. In this guide, we'll be using Jupyter notebooks to demonstrate markdown, however note that markdown is not Jupyter specific. Many other services and products use it to allow easy text formatting. Jupyter Notebook Markdown Cheatsheet April 9, 2020 SqlBak mike Jupyter Notebook is a great tool for data analysis. And one of its greatest features is that you can easily combine runnable code with rich-text annotations. Jupyter Notebook Cheat Sheet This Jupyter Notebook cheat sheet will help you to find your way around the well-known Notebook App, a subproject of Project Jupyter. You'll probably know the Jupyter notebooks pretty well - it's one of the most well-known parts of the Jupyter ecosystem! Sometimes markdown doesn’t make line breaks when you want them. To force a linebreak, use the following code: Indenting Use the greater than sign followed by a space, for example: Text that will be indented when the Markdown is rendered. Any subsequent text is indented until the next carriage return. Here’s how to format Markdown cells in Jupyter notebooks: HeadingsUse the number sign (#) followed by a blank space for notebook titles and section headings: # for titles ## for major headings ### for subheadings #### for 4th level subheadings; EmphasisUse the following code to emphasize text: Bold text: string or.string.

What is Markdown?

Markdown is a human readable syntax (also referred to as a markup language) for formatting text documents. Markdown can be used to produce nicely formatted documents including PDFs and web pages.

When you format text using Markdown in a document, it is similar to using the format tools (e.g. bold, heading 1, heading 2) in a word processing tool like Microsoft Word or Google Docs. However, instead of using buttons to apply formatting, you use syntax such as **this syntax bolds text in markdown** or # Here is a heading.

Markdown syntax allows you to format text in many ways, such as making headings, bolding and italicizing words, creating bulleted lists, adding links, formatting mathematical symbols and making tables. These options allow you to format text in visually appealing and organized ways to present your ideas.

You can use Markdown to format text in many different tools including GitHub.com, R using RMarkdown, and Jupyter Notebook, which you will learn more about this page.

Data Tip: Learn more about how you can use Markdown to format text and document workflows in a variety of tools.

Markdown in Jupyter Notebook

A great benefit of Jupyter Notebook is that it allows you to combine both code (e.g. Python) and Markdown in one document, so that you can easily document your workflows.

A Jupyter Notebook file uses cells to organize content, and it can contain both cells that render text written using the Markdown syntax as well as cells that contain and run Python code.

Thus, you can use a combination of Markdown and Python code cells to organize and document your Jupyter Notebook for others to easily read and follow your workflow.

Data Tip: Learn more about Markdown for Jupyter Notebook.

If you render your Jupyter Notebook file to HTML or PDF, this Markdown will appear as formatted text in the output document.

Data Tip: In fact, this web page that you are reading right now is generated from a Markdown document! On this page, you will learn the basic syntax of Markdown.

Benefits of Markdown for Earth Data Science

Being able to include both Markdown and code (e.g. Python) cells in a Jupyter Notebook file supports reproducible science by allowing you to:

• Document your workflow: You can add text to the document that describes the steps of your processing workflow (e.g. how data is being processed and what results are produced).
• Describe your data: You can describe the data that you are using (e.g. source, pre-processing, metadata).
• Interpret code outputs: You can add some text that interprets or discusses the outputs.

all in one document!

When used effectively, Markdown documentation can help anyone who opens your Jupyter Notebook to follow, understand and even reproduce your workflow.

Format Text in Jupyter Notebook with Markdown

Markdown Cells in Jupyter Notebook

In the previous chapter on Jupyter Notebook, you learned how to add new Markdown cells to your Jupyter Notebook files using Menu tools and Keyboard Shortcuts to create new cells.

You also learned how to change the default type of the cell by clicking in the cell and selecting a new cell type (e.g. Markdown) in the cell type menu in the toolbar. Furthermore, you learned that in a Jupyter Notebook file, you can double-click in any Markdown cell to see the syntax, and then run the cell again to see the Markdown formatting.

Note: if you type text in a Markdown cell with no additional syntax, the text will appear as regular paragraph text. You can add additional syntax to that text to format it in different ways.

On this page, you will learn basic Markdown syntax that you can use to format text in Jupyter Notebook files.

Section Headers

You can create a heading using the pound (#) sign. For the headers to render properly, there must be a space between the # and the header text.

Heading one is denoted using one # sign, heading two is denoted using two ## signs, etc, as follows:

Here is a sample of the rendered Markdown:

Heading Three

Heading Four

Note: the titles on this page are actually formatted using Markdown (e.g. the words Section Headers above are formatted as a heading two).

Lists

You can also use Markdown to create lists using the following syntax:

It will render as follows:

• This is a bullet list
• This is a bullet list
• This is a bullet list

1. And you can also create ordered lists
2. by using numbers
3. and listing new items in the lists
4. on their own lines

Notice that you have space between the * or 1. and the text. The space triggers the action to create the list using Markdown.

Bold and Italicize

You can also use ** to bold or * to italicize words. To bold and italicize words, the symbols have to be touching the word and have to be repeated before and after the word using the following syntax:

It will render as follows:

These are italicized words, not a bullet listThese are bold words, not a bullet list

• This is a bullet item with bold words
• This is a bullet item with italicized words

Highlight Code

If you want to highlight a function or some code within a plain text paragraph, you can use one backtick on each side of the text like this:

which renders like this:

Here is some code!

The symbol used is the backtick, or grave; not an apostrophe (on most US keyboards, it is on the same key as the tilde (~)).

Horizontal Lines (Rules)

You can also create a horizontal line or rule to highlight a block of Markdown syntax (similar to the highlighting a block of code using the backticks):

which renders like this:

Here is some important text!

Hyperlinks

You can also use HTML in Markdown cells to create hyperlinks to websites using the following syntax:

<a href='url' target='_blank'>hyperlinked words</a>

You can identify the words that will be hyperlinked (i.e. prompt a web page to open when clicked) by replacing hyperlinked words in the example above.

For example, the following syntax:

Our program website can be found at <a href='http://earthdatascience.org' target='_blank'>this link</a>.

will render as follows with this link as the hyperlinked words:

Our program website can be found at this link.

Render Images

You can also use Markdown to link to images on the web using the following syntax:

![alt text here](url-to-image-here)

The alt text is the alternative text that appears if an image fails to load on webpage; it is also used by screen-reading tools to identify the image to users of the screen-reading tools.

For example, the following syntax:

![Markdown Logo is here.](https://www.fullstackpython.com/img/logos/markdown.png)

will render as follows with an alt text of Markdown Logo is here.:

Local Images Using Relative Computer Paths

You can also add images to a Markdown cell using relative paths to files in your directory structure using:

![alt text here](path-to-image-here)

For relative paths (images stored on your computer) to work in Jupyter Notebook, you need to place the image in a location on your computer that is RELATIVE to your .ipynb file. This is where good file management becomes extremely important.

For a simple example of using relative paths, imagine that you have a subdirectory named images in your earth-analytics directory (i.e. earth-analytics/images/).

If your Jupyter Notebook file (.ipynb) is located in root of this directory (i.e. earth-analytics/notebook.ipynb), and all images that you want to include in your report are located in the images subdirectory (i.e. earth-analytics/images/), then the path that you would use for each image is:

images/image-name.png

If all of your images are in the images subdirectory, then you will be able to easily find them. This also follows good file management practices because all of the images that you use in your report are contained within your project directory.

Data tip: There are many free Markdown editors out there! The atom.io editor is a powerful text editor package by GitHub, that also has a Markdown renderer that allows you to preview the rendered Markdown as you write.

Additional Resources

Practice Your Markdown Skills

1. Open or create a new Jupyter Notebook file.

2. Add a new Markdown cell and include:
   • A title for the notebook (e.g. Intro to Earth Analytics - Chapter Four)
   • A bullet list with:
     • A bold word for Author: and then add text for your name.
     • A bold word for Date: and then add text for today’s date.
3. Add another Markdown cell and include:
   • A list of your top three favorite foods (e.g. blueberries, chocolate bars, avocados).
     • Italicize the first item in your list.
     • Add a hyperlink (i.e. webpages) for the second item in your list (include the name of the food in the title of the hyperlink).
     • Add an image for the last item in your list (include the name in the alt text of the image).

It’s possible to control which content shows up in your book. For example,you may want to display a complex visualization to illustrate an idea, but don’twant the page to be cluttered with a large code cell that generated the visualization.In other cases, you may want to remove a code cell entirely.

In this case, you have two options:

• Hiding content provides a button that lets readers reveal the content.

• Removing content prevents it from making it into your book. Itwill be entirely gone (though still present in the source files)

There are two ways to hide content:

• To hide Markdown, use the {toggle} directive.

• To hide or remove code cells or their outputs, use notebook cell tags.

We’ll cover each alternative below.

Jupyter Lab Markdown Preview

Hide Markdown using MyST Markdown¶

There are two ways to hide Markdown content

• you can use the {toggle} directive to hide arbitrary blocks of content

• you can use the dropdown class with admonitions to turn them into dropdowns

Both allow you to wrap chunks of Markdown in a button that lets users showand hide the content.

The {toggle} directive¶

You can activate a toggleable behavior in Markdown with the {toggle}directive like so:

This results in:

Some hidden toggle content!

Note that if you’d like to show the toggle content by default, you canadd the :show: flag when you use {toggle}, like so:

Toggle admonition content with dropdowns¶

You can also add toggle buttons to admonition blocks, effectively making themdropdown blocks. Users will see the admonition title, but will need to clickin order to reveal the content. To do so, add the dropdown class to any admonition.For example, the code

results in:

Click the button to reveal!

Some hidden toggle content!

See Dropdown admonitions for more information on admonition dropdowns.

Hide code cell content¶

You can hide most cell elements of a page. The sections below describe howto hide each using cell tags in MyST Markdown.If you’re working with .ipynb files, see the cell tags guideon adding cell tags to notebooks in Jupyter Notebook or JupyterLab.

If an element is hidden, Jupyter Book will display a small button to the right of theold location for the hidden element. If a user clicks the button,the element will be displayed.

Hide cell inputs¶

If you add the tag hide-input to a cell, then Jupyter Book will hide the cell butdisplay the outputs.

Here’s an example of cell metadata that would trigger the “hide code” behavior:

For example, notice the cell below contains the hide-input tag:

Note how we only see the output by default. Now try clicking the buttonto the right of the empty spot above!

Hide cell outputs¶

You can also hide the outputs of a cell. For example, if you’d like to ask users tothink about what the output will look like first before viewing an answer. To do so,add the following tag to your cell:

Hide entire code cells¶

If you’d like to hide the whole code cell (both inputs and outputs) just add thistag to the cell metadata, like so:

Removing code cell content¶

In the above examples, we are only hiding parts of the cell, with the optionthat readers can reveal them if they wish. However, if you’d like to completely removethe respective parts, so that their contents do not make it into the book’s HTML, you mayuse the appropriate remove- tags, i.e. remove-input, remove-output and remove-cell.

Remove cell inputs¶

The following cell has its inputs removed with remove-input. Note that inthis case, there is no button available to show the input contents,the entire input cell is gone!

Remove cell outputs¶

Similar to hiding inputs, it is also possible to hide the outputsof a cell with remove-output:

Remove an entire code cell¶

You can also remove both the inputs and outputs of a cell, in which case itwon’t show up in your book at all. These cells remain in the notebook file itself,so they’ll show up if readers click on a JupyterHub or Binder link from a page.

To remove both the inputs and outputs of a cell, add the tag remove-cell to the tagsof the cell. Here’s an example of cell metadata that would trigger the “remove cell” behavior:

These cells will be entirely removed from each book page - remember that if you’d like tooptionally display the inputs of a cell instead, you should use the hide-input tag.

For example, there’s a cell below this text that won’t make it into the final book,because it has been removed!

Jupiter Lab Markdown Cheat Sheet Printable

Remove empty cells¶

You don’t need to do anything to remove empty cells from your pages.Jupyter Book will remove these automatically. Any cell with onlywhitespace will be removed.

Jupiter Lab Markdown Cheat Sheet Download

For example, in the notebook for this page there are two cells above this text.Both only contain whitespace. Both are gone fromthe final output.