{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Format Text With Markdown\n", "\n", "Jenny Palomino \n", "Leah Wasser \n", "2025-04-18\n", "\n", "## What is Markdown?\n", "\n", "`Markdown` is a human readable syntax (also referred to as a markup\n", "language) for formatting text documents. `Markdown` can be used to\n", "produce nicely formatted documents including PDFs and web pages.\n", "\n", "When you format text using `Markdown` in a document, it is similar to\n", "using the format tools (e.g. bold, heading 1, heading 2) in a word\n", "processing tool like Microsoft Word or Google Docs. However, instead of\n", "using buttons to apply formatting, you use syntax such as\n", "`**this syntax bolds text in markdown**` or `# Here is a heading`.\n", "\n", "`Markdown` syntax allows you to format text in many ways, such as making\n", "headings, bolding and italicizing words, creating bulleted lists, adding\n", "links, formatting mathematical symbols and making tables. These options\n", "allow you to format text in visually appealing and organized ways to\n", "present your ideas.\n", "\n", "You can use Markdown to format text in many different tools including\n", "GitHub.com,\n", "R using\n", "RMarkdown,\n", "and Jupyter Notebook, which you will learn more about this page.\n", "\n", "> **Data Tip**\n", ">\n", "> Learn more about how you can use\n", "> Markdown\n", "> to format text and document workflows in a variety of tools.\n", "\n", "### Markdown in Jupyter Notebook\n", "\n", "A great benefit of `Jupyter Notebook` and other interactive computing\n", "notebooks is that it allows you to combine both code (e.g. `Python`) and\n", "`Markdown` in one document, so that you can easily document your\n", "workflows.\n", "\n", "A `Jupyter Notebook` file uses cells to organize content, and it can\n", "contain both cells that render text written using the `Markdown` syntax\n", "as well as cells that contain and run `Python` code.\n", "\n", "Thus, you can use a combination of `Markdown` and `Python` code cells to\n", "organize and document your `Jupyter Notebook` for others to easily read\n", "and follow your workflow." ], "id": "85bb7ff9-aca4-4193-bd03-770bc7fb3ff5" }, { "cell_type": "raw", "metadata": { "raw_mimetype": "text/html" }, "source": [ "
" ], "id": "9029958b-c2b6-4a3c-9c8c-6dd87f4276e7" }, { "cell_type": "markdown", "metadata": {}, "source": [ "\n", "\"An" ], "id": "41a10008-7c94-4b9f-9c5e-9be9fb33d910" }, { "cell_type": "raw", "metadata": { "raw_mimetype": "text/html" }, "source": [ "
" ], "id": "218e5043-6e89-4929-bc0b-5baec70d705f" }, { "cell_type": "markdown", "metadata": {}, "source": [ "An example Markdown cell in Jupyter Notebook." ], "id": "d54eebb3-4f77-4cfa-84df-b32cdd3e8361" }, { "cell_type": "raw", "metadata": { "raw_mimetype": "text/html" }, "source": [ "
" ], "id": "b3afff2c-7b5c-4112-8d58-b18d68a327c6" }, { "cell_type": "raw", "metadata": { "raw_mimetype": "text/html" }, "source": [ "
" ], "id": "977de094-e901-421f-98b4-09976024bc4d" }, { "cell_type": "markdown", "metadata": {}, "source": [ "> **Data Tip**\n", ">\n", "> Learn more about\n", "> Markdown\n", "> for Jupyter Notebook.\n", "\n", "If you render your `Jupyter Notebook` file to HTML or PDF, this\n", "`Markdown` will appear as formatted text in the output document.\n", "\n", "> **Data Tip**\n", ">\n", "> In fact, this web page that you are reading right now is generated\n", "> from a `Markdown` document! On this page, you will learn the basic\n", "> syntax of `Markdown`.\n", "\n", "### Benefits of Markdown for Earth Data Science\n", "\n", "Being able to include both `Markdown` and code (e.g. `Python`) cells in\n", "a `Jupyter Notebook` file supports reproducible science by allowing you\n", "to:\n", "\n", "- Document your workflow: You can add text to the document that\n", " describes the steps of your processing workflow (e.g. how data is\n", " being processed and what results are produced).\n", "- Describe your data: You can describe the data that you are using\n", " (e.g. source, pre-processing, metadata).\n", "- Interpret code outputs: You can add some text that interprets or\n", " discusses the outputs.\n", "\n", "all in one document!\n", "\n", "When used effectively, `Markdown` documentation can help anyone who\n", "opens your `Jupyter Notebook` to follow, understand and even reproduce\n", "your workflow.\n", "\n", "## Format Text in Jupyter Notebook with Markdown\n", "\n", "### Markdown Cells in Jupyter Notebook\n", "\n", "In the previous chapter on `Jupyter Notebook`, you learned how to add\n", "new `Markdown` cells to your `Jupyter Notebook` files using Menu tools\n", "and Keyboard Shortcuts to create new cells.\n", "\n", "| Function | Keyboard Shortcut | Menu Tools |\n", "|------------------------|------------------------|------------------------|\n", "| Create new cell | Esc + a (above), Esc + b (below) | Insert→ Insert Cell Above OR Insert → Insert Cell Below |\n", "| Copy Cell | c | Copy Key |\n", "| Paste Cell | v | Paste Key |\n", "\n", "You also learned how to change the default type of the cell by clicking\n", "in the cell and selecting a new cell type (e.g. `Markdown`) in the cell\n", "type menu in the toolbar. Furthermore, you learned that in a\n", "`Jupyter Notebook` file, you can double-click in any `Markdown` cell to\n", "see the syntax, and then run the cell again to see the `Markdown`\n", "formatting.\n", "\n", "**Note:** if you type text in a `Markdown` cell with no additional\n", "syntax, the text will appear as regular paragraph text. You can add\n", "additional syntax to that text to format it in different ways.\n", "\n", "On this page, you will learn basic `Markdown` syntax that you can use to\n", "format text in `Jupyter Notebook` files.\n", "\n", "## Section Headers\n", "\n", "You can create a heading using the pound (`#`) sign. For the headers to\n", "render properly, there must be a space between the `#` and the header\n", "text.\n", "\n", "Heading one is denoted using one `#` sign, heading two is denoted using\n", "two `##` signs, etc, as follows:\n", "\n", "``` markdown\n", "## Heading Two\n", "\n", "### Heading Three\n", "\n", "#### Heading Four\n", "```\n", "\n", "Here is a sample of the rendered `Markdown`:\n", "\n", "### Heading Three\n", "\n", "#### Heading Four\n", "\n", "**Note**: the titles on this page are actually formatted using\n", "`Markdown` (e.g. the words **Section Headers** above are formatted as a\n", "heading two).\n", "\n", "## Lists\n", "\n", "You can also use `Markdown` to create lists using the following syntax:\n", "\n", "``` markdown\n", "* This is a bullet list\n", "* This is a bullet list\n", "* This is a bullet list\n", "\n", "\n", "1. And you can also create ordered lists\n", "2. by using numbers\n", "3. and listing new items in the lists \n", "4. on their own lines\n", "```\n", "\n", "It will render as follows:\n", "\n", "- This is a bullet list\n", "- This is a bullet list\n", "- This is a bullet list\n", "\n", "1. And you can also create ordered lists\n", "2. by using numbers\n", "3. and listing new items in the lists\n", "4. on their own lines\n", "\n", "Notice that you have space between the `*` or `1.` and the text. The\n", "space triggers the action to create the list using `Markdown`.\n", "\n", "## Bold and Italicize\n", "\n", "You can also use `**` to bold or `*` to italicize words. To bold and\n", "italicize words, the symbols have to be touching the word and have to be\n", "repeated before and after the word using the following syntax:\n", "\n", "``` markdown\n", "*These are italicized words, not a bullet list*\n", "**These are bold words, not a bullet list**\n", "\n", "* **This is a bullet item with bold words**\n", "* *This is a bullet item with italicized words*\n", "```\n", "\n", "It will render as follows:\n", "\n", "*These are italicized words, not a bullet list* **These are bold words,\n", "not a bullet list**\n", "\n", "- **This is a bullet item with bold words**\n", "- *This is a bullet item with italicized words*\n", "\n", "## Highlight Code\n", "\n", "If you want to highlight a function or some code within a plain text\n", "paragraph, you can use one backtick on each side of the text like this:\n", "\n", "``` markdown\n", "`Here is some code!`\n", "```\n", "\n", "which renders like this:\n", "\n", "`Here is some code!`\n", "\n", "The symbol used is the backtick, or grave; not an apostrophe (on most US\n", "keyboards, it is on the same key as the tilde (~)).\n", "\n", "## Horizontal Lines (Rules)\n", "\n", "You can also create a horizontal line or rule to highlight a block of\n", "`Markdown` syntax (similar to the highlighting a block of code using the\n", "backticks):\n", "\n", "``` markdown\n", "***\n", "\n", "Here is some important text!\n", "\n", "***\n", "```\n", "\n", "which renders like this:\n", "\n", "------------------------------------------------------------------------\n", "\n", "Here is some important text!\n", "\n", "------------------------------------------------------------------------\n", "\n", "## Hyperlinks\n", "\n", "You can also use HTML in `Markdown` cells to create hyperlinks to\n", "websites using the following syntax:\n", "\n", "`hyperlinked words`\n", "\n", "You can identify the words that will be hyperlinked (i.e. prompt a web\n", "page to open when clicked) by replacing `hyperlinked words` in the\n", "example above.\n", "\n", "For example, the following syntax:\n", "\n", "`Our program website can be found at this link.`\n", "\n", "will render as follows with `this link` as the hyperlinked words:\n", "\n", "Our program website can be found at\n", "this link.\n", "\n", "## Render Images\n", "\n", "You can also use `Markdown` to link to images on the web using the\n", "following syntax:\n", "\n", "`![alt text here](url-to-image-here)`\n", "\n", "The alt text is the alternative text that appears if an image fails to\n", "load on webpage; it is also used by screen-reading tools to identify the\n", "image to users of the screen-reading tools.\n", "\n", "For example, the following syntax:\n", "\n", "`![Markdown Logo is here.](https://www.fullstackpython.com/img/logos/markdown.png)`\n", "\n", "will render as follows with an alt text of `Markdown Logo is here.`:\n", "\n", "
\n", "\n", "
Markdown Logo is here.
\n", "
\n", "\n", "### Local Images Using Relative Computer Paths\n", "\n", "You can also add images to a `Markdown` cell using relative paths to\n", "files in your directory structure using:\n", "\n", "`![alt text here](path-to-image-here)`\n", "\n", "For relative paths (images stored on your computer) to work in\n", "`Jupyter Notebook`, you need to place the image in a location on your\n", "computer that is RELATIVE to your `.ipynb` file. This is where good file\n", "management becomes extremely important.\n", "\n", "For a simple example of using relative paths, imagine that you have a\n", "subdirectory named `images` in your `earth-analytics` directory\n", "(i.e. `earth-analytics/images/`).\n", "\n", "If your `Jupyter Notebook` file (`.ipynb`) is located in root of this\n", "directory (i.e. `earth-analytics/notebook.ipynb`), and all images that\n", "you want to include in your report are located in the `images`\n", "subdirectory (i.e. `earth-analytics/images/`), then the path that you\n", "would use for each image is:\n", "\n", "`images/image-name.png`\n", "\n", "If all of your images are in the `images` subdirectory, then you will be\n", "able to easily find them. This also follows good file management\n", "practices because all of the images that you use in your report are\n", "contained within your project directory.\n", "\n", "> **Data tip**\n", ">\n", "> There are many free `Markdown` editors out there! The\n", "> atom.io editor is a\n", "> powerful text editor package by GitHub, that also has a `Markdown`\n", "> renderer that allows you to preview the rendered `Markdown` as you\n", "> write.\n", "\n", "## Additional Resources\n", "\n", "- GitHub\n", " Guide on Markdown\n", "- \n", " Jupyter Notebook Markdown Resources\n", "\n", "> **Practice Your Markdown Skills**\n", ">\n", "> 1. Open or create a new `Jupyter Notebook` file.\n", ">\n", "> 2. Add a new `Markdown` cell and include:\n", ">\n", "> - A title for the notebook\n", "> (e.g. `Intro to Earth Analytics - Chapter Four`)\n", "> - A **bullet list** with:\n", "> - A bold word for `Author:` and then add text for your name.\n", "> - A bold word for `Date:` and then add text for today’s\n", "> date.\n", ">\n", "> 3. Add another `Markdown` cell and include:\n", ">\n", "> - A list of your top three favorite foods (e.g. blueberries,\n", "> chocolate bars, avocados).\n", "> - Italicize the first item in your list.\n", "> - Add a hyperlink (i.e. webpages) for the second item in\n", "> your list (include the name of the food in the title of\n", "> the hyperlink).\n", "> - Add an image for the last item in your list (include the\n", "> name in the alt text of the image)." ], "id": "bffca6e2-5ee9-4c23-90a5-6e3fea3d3d4e" } ], "nbformat": 4, "nbformat_minor": 5, "metadata": { "kernelspec": { "name": "python3", "display_name": "Python 3 (ipykernel)", "language": "python", "path": "/usr/share/miniconda/envs/learning-portal/share/jupyter/kernels/python3" }, "language_info": { "name": "python", "codemirror_mode": { "name": "ipython", "version": "3" }, "file_extension": ".py", "mimetype": "text/x-python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.10.17" } } }