diff --git a/foundations/markdown.ipynb b/foundations/markdown.ipynb new file mode 100644 index 000000000..3990aa2fb --- /dev/null +++ b/foundations/markdown.ipynb @@ -0,0 +1,288 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "![](https://github.com/dcurtis/markdown-mark/raw/master/png/208x128-solid.png \"markdown-mark logo\")\n", + "\n", + "# Markdown in Jupyter" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "---" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Overview" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Prerequisites\n", + "| Concepts | Importance | Notes |\n", + "| --- | --- | --- |\n", + "| | | |\n", + "\n", + "- **Time to learn**: " + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "---" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Markdown Cells\n", + "Markdown is a convenient way to create formatted text using a simple syntax. There are different flavors of markdown, but the [basics](https://daringfireball.net/projects/markdown/basics) are supported across the board and generally cover 80% of the use cases. HTML is also valid in markdown cells. In fact, all of the text and the header of this notebook are markdown/HTML. With markdown you can create headings, embed images, link to other pages, create lists, and more. We aren't going to exhaustively cover markdown, but the essentials can help you make really nice notebooks. Remember, the better your documentation, the more you'll thank yourself later. Think of the notebook as a lab notebook.\n", + "\n", + "#### Basic Text Formatting\n", + "Text can be made **bold** or *italic* by enclosing it in astericks. Notice that a preview even renders in the cell to help you see the formatting that will be applied!\n", + "\n", + "```\n", + "**This text will be bold**\n", + "*This text will be in italics*\n", + "```\n", + "\n", + "---\n", + "\n", + "**This text will be bold**\n", + "\n", + "*This text will be in italics*" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### Headings\n", + "You can create headings by prepending the text with a number of octothorpes (that's these: #). These go up to five levels deep!\n", + "\n", + "```\n", + "# Heading\n", + "## Sub-Heading\n", + "### Subsub-Heading\n", + "#### Subsubsub-Heading\n", + "##### Subsubsubsub-Heading\n", + "```\n", + "\n", + "---\n", + "\n", + "# Heading\n", + "## Sub-Heading\n", + "### Subsub-Heading\n", + "#### Subsubsub-Heading\n", + "##### Subsubsubsub-Heading\n", + "\n", + "---\n", + "\n", + "**PS** - Notice the horizontal lines helping separate content above? Create them with `---`" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### Lists\n", + "You can create ordered and unordered lists with markdown in a format that is much more human readable and editable than making an HTML list. For ordered lists the markdown rendering will even take care of numbering, just use all ones. Remember, let the computer do your work! Sublist formatting is also handled in a sane way automatically.\n", + "\n", + "---\n", + "\n", + "```\n", + "* This is an unordered list\n", + "* It is useful for many things\n", + " * Grocery lists\n", + " * Plans to take over the world\n", + " * Large plans may require multiple lists\n", + "```\n", + "\n", + "---\n", + "\n", + "* This is an unordered list\n", + "* It is useful for many things\n", + " * Grocery lists\n", + " * Plans to take over the world\n", + " * Large plans may require multiple lists\n", + "---\n", + "\n", + "```\n", + "1. Create an ordered list\n", + " 1. Use numbers\n", + " 1. Let the computer handle numbering\n", + " 1. Look super organized\n", + "1. Take over the world\n", + "```\n", + "\n", + "---\n", + "\n", + "1. Create an ordered list\n", + " 1. Use numbers\n", + " 1. Let the computer handle numbering\n", + " 1. Look super organized\n", + "1. Take over the world\n", + "---" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### Other Text Formatting\n", + "There are a few other handy text formatting tricks that don't really get their own section, but are nice to see.\n", + "\n", + "Blockquoting is handy for inserting quotes from papers, documents, etc. Just prepend all of the lines with >.\n", + "\n", + "```\n", + "> I was born not knowing and have had only a little time to\n", + "> change that here and there.\n", + "> \\- Richard P. Feynman\n", + "```\n", + "\n", + "---\n", + "\n", + "> I was born not knowing and have had only a little time to\n", + "> change that here and there.\n", + "> \\- Richard P. Feynman\n", + "\n", + "---\n", + "\n", + "The notebook environment also supports so called GitHub flavored markdown. You can tripple quote code blocks and get a nicely formatted output. Providing the langauge even provides syntax highlighting.\n", + "\n", + "---\n", + "\n", + "
\n",
+    "```python\n",
+    "import time \n",
+    "\n",
+    "for i in range(10, 0, -1):\n",
+    "    print(i)\n",
+    "    time.sleep(1)\n",
+    "print(\"Blast off!\")\n",
+    "```\n",
+    "
\n", + "\n", + "---\n", + "\n", + "```python\n", + "import time \n", + "\n", + "for i in range(10, 0, -1):\n", + " print(i)\n", + " time.sleep(1)\n", + "print(\"Blast off!\")\n", + "```\n", + "\n", + "---" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### Tables\n", + "\n", + "Making tables is horrible in HTML. Markdown (multi-markdown actually) makes really good looking tables with simple text input.\n", + "\n", + "---\n", + "```\n", + "| Date | Max Temp | Min Temp |\n", + "| ---- | -------- | -------- |\n", + "| 4/12 | 75 | 65 |\n", + "| 4/13 | 80 | 68 |\n", + "| 4/14 | 68 | 50 |\n", + "```\n", + "\n", + "---\n", + "\n", + "| Date | Max Temp | Min Temp |\n", + "| ---- | -------- | -------- |\n", + "| 4/12 | 75 | 65 |\n", + "| 4/13 | 80 | 68 |\n", + "| 4/14 | 68 | 50 |\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### Images\n", + "Inserting images in markdown is a one liner!\n", + "```\n", + "![alt text](/path/to/img.jpg \"Title\")\n", + "```\n", + "\n", + "![MetPy Logo](https://github.com/Unidata/MetPy/raw/master/docs/_static/metpy_150x150_white_bg.png \"MetPy's Logo\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### Equations\n", + "Notebooks are MathJax-aware, so using a subset of the $\\LaTeX$ syntax, you can easily render complex equations in notebook cells. We don't have time to go into the details of the syntax, but you can find [many tutorials](http://www.math.harvard.edu/texman/) on the topic. Showing a few examples will give you the idea though!\n", + "\n", + "To put equations inline with text enclose them in `$`, to put them on separate lines enclose them in `$$`.\n", + "\n", + "Let's start with a simple example, Newton's second law:\n", + "```\n", + "$$F = m a$$\n", + "```\n", + "\n", + "$$F = m a$$\n", + "\n", + "---\n", + "\n", + "We can also typeset much more complicated equations with a little more syntax effort:\n", + "```\n", + "$$\\left( \\frac{Dv}{Dt} \\right) = -2 \\Omega u \\text{sin}\\phi - \\frac{u^2}{a} \\text{tan}\\phi$$\n", + "```\n", + "\n", + "$$\\left( \\frac{Dv}{Dt} \\right) = -2 \\Omega u \\text{sin}\\phi - \\frac{u^2}{a} \\text{tan}\\phi$$\n", + "\n", + "---\n", + "\n", + "```\n", + "$$\\frac{\\partial\\zeta}{\\partial t} = - V \\cdot \\nabla(\\zeta + f) - \\omega \\frac{\\partial \\zeta}{\\partial p}\n", + "- (\\zeta + f) \\nabla \\cdot V + k \\cdot \\left(\\frac{\\partial V}{\\partial p} \\times \\nabla \\omega \\right)$$\n", + "```\n", + "\n", + "$$\\frac{\\partial\\zeta}{\\partial t} = - V \\cdot \\nabla(\\zeta + f) - \\omega \\frac{\\partial \\zeta}{\\partial p}\n", + "- (\\zeta + f) \\nabla \\cdot V + k \\cdot \\left(\\frac{\\partial V}{\\partial p} \\times \\nabla \\omega \\right)$$" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.8.12" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} diff --git a/foundations/markdown.md b/foundations/markdown.md deleted file mode 100644 index af786d6ad..000000000 --- a/foundations/markdown.md +++ /dev/null @@ -1,9 +0,0 @@ -# Formatted text in the notebook with Markdown - -```{note} -This content is under construction! -``` - -This section will give a tutorial on formatting text with Markdown: the simple, human-readable text language used extensively in Jupyter notebooks, GitHub discussions, and elsewhere. - -We will show how this useful both in notebooks and other places like GitHub issues.