This tutorial walks you through how to format text using
Markdown to document your workflows in
Jupyter Notebook files.
At the end of this activity, you will be able to:
- Explain the role
Markdownsyntax for documentation
- Create headings using
- Italicize and bold text using
- Render images using
Markdown is a human readable syntax 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 allows you to format text - such as making headings, bolding and italicizing words, creating bulleted lists, adding links, formatting mathematical symbols and making tables.
Data Tip: Learn more about Markdown
Markdown Syntax in Jupyter Notebook files
Jupyter Notebook allows you to combine code (e.g.
Markdown in one document using cells. A
Jupyter Notebook file can contain cells that render text written using the
Markdown syntax as well as cells that contain and run
You can use
Markdown in a
Jupyter Notebook file for many different purposes. It could be used to:
- Document your workflow: You can add text to the document that describes the steps that you incorporated into 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 may even add some text that interprets or discusses the outputs.
If you render your
Jupyter Notebook file to HTML or PDF, this
Markdown will appear as text on the output document.
Data Tip: This web page that you are reading right now is generated from a markdown document. In this tutorial, we cover the basic syntax of markdown.
Get to Know the Markdown Syntax
Markdown is simple plain text, that is styled using special characters, including:
#: a header element
**: bold text
*: italic text
Explore using some basic
Emphasize Code and Words in Markdown
When you type text in a
Markdown document with no additional syntax, the text will appear as paragraph text. You can add additional syntax to that text to format it in different ways.
For example, 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 (
`code-goes-here` ), like this:
`Here is some code`.
This is the backtick, or grave; not an apostrophe (on most US keyboards, it is on the same key as the tilde (~)).
To add emphasis to other text, you can use also use the following syntax to bold or italicize words.
The use of the backtick (e.g. `text` ) will be reserved for denoting code. To add emphasis to other text, use **bold** or *italics*.
Notice that this sentence uses both a code highlight (
text), bolding (text) and italics (text).
Markdown, it looks like this:
The use of the highlight (
text ) will be reserve for denoting code when used in text. To add emphasis to other text use bold or italics.
Horizontal Lines (Rules)
You can also create a horizonal line or rule to highlight a block of
Markdown syntax (similar to the highlighting a block of code using ` `):
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:
`## Heading Two
Here is the rendered
![alt text here](path-to-image-here)
If you want to embed an image from a website, you can use the following syntax:
![Markdown Logo is here.](https://www.fullstackpython.com/img/logos/markdown.png)
It will look like this:
For relative paths (images stored on your computer) to work in
Python, you need to place the image in the right location on your computer - RELATIVE to your
.ipynb file. This is where good file management becomes extremely important.
For a simple example of using relative paths, create a directory named
images in your
Jupyter Notebook file (
.ipynb) is located in root of this directory, and all images that you want to include in your report are located in the
images directory within
earth-analytics, then the path that you would use for each image is:
If all of your images are in the
images directory, 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.