How_to_use_markdown_cells.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "225c06b6",
   "metadata": {
    "colab_type": "text",
    "id": "view-in-github"
   },
   "source": [
    "<a href=\"https://colab.research.google.com/github/UCD-Physics/Python-HowTos/blob/main/How_to_use_markdown_cells.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b557343c",
   "metadata": {
    "id": "b557343c"
   },
   "source": [
    "# Formatting your Jupyter Notebooks with Markdown\n",
    "\n",
    "Markdown is a text-based formatting language used to format Jupyter Notebook markdown cells (make sure you change the cell type from 'Code' to 'Markdown').\n",
    "\n",
    "Markdown allows you to provide additional information to explain and supplement the code and results of any calculations. It allows headings, subheadings, bold and italic fonts, tables, lists, sample code, figures etc to be included. \n",
    "\n",
    "In addition LaTeX equations can be embedded and rendered in Markdown cells, making Jupyter Notebooks extremely useful for documenting scientific calculations. \n",
    "\n",
    "A markdown reference is available [here](https://www.markdownguide.org/basic-syntax/) and a\n",
    "Jupyter Notebook Markdown Cheat Sheet can be found [here](https://notebook.community/tschinz/iPython_Workspace/00_Admin/CheatSheet/Markdown%20CheatSheet).\n",
    "\n",
    "To print a Jupyter Notebook to a PDF first select `File -> Print Preview` and then print the preview to PDF. It is possible to download in other formats (such as html, markdown) but the download as PDF option downloads a .tex version and the runs LaTeX on the .tex file.\n",
    "\n",
    "Topics covered in this notebook:\n",
    " - Titles and subtitles\n",
    " - Formatting text\n",
    " - LaTeX equations\n",
    " - Line breaks and rules\n",
    " - Code\n",
    " - Lists\n",
    " - Tables\n",
    " - Links\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "Z--JzmfND61r",
   "metadata": {
    "id": "Z--JzmfND61r"
   },
   "source": [
    "## Titles and Subtitles \n",
    "\n",
    "The following markdown code \n",
    "```markdown\n",
    "# Title H1\n",
    "\n",
    "## Title H2\n",
    "\n",
    "### Title H3\n",
    "\n",
    "#### Title H4\n",
    "```\n",
    "\n",
    "produces:\n",
    "\n",
    "\n",
    "# Title H1\n",
    "\n",
    "## Title H2\n",
    "\n",
    "### Title H3\n",
    "\n",
    "#### Title H4"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "33e6424c",
   "metadata": {},
   "source": [
    "<a id='Formatting_text'></a>\n",
    "\n",
    "## Formatting text <a id='Formatting_Text'></a>\n",
    "\n",
    "The following markdown code:\n",
    "```markdown\n",
    "*single asterix* or _single underscore_ will emphasise text in italics \n",
    "\n",
    "**double asterix** or __double underscore__ will emphasise text in bold.\n",
    "\n",
    "**_double asterix with underscore_** will emphasise text in bold and italics\n",
    "\n",
    "~~double tilde~~ will strikethrough text.\n",
    "```\n",
    "produces:\n",
    "\n",
    "*single asterix* or _single underscore_ will emphasise text in italics \n",
    "\n",
    "**double asterix** or __double underscore__ will emphasise text in bold.\n",
    "\n",
    "**_double asterix with underscore_** will emphasise text in bold and italics\n",
    "\n",
    "~~double tilde~~ will strikethrough text.\n",
    "\n",
    "\n",
    "---\n",
    "\n",
    "In addition, there is a block-quote feature using \">\"\n",
    "\n",
    "The following markdown code:\n",
    "```markdown\n",
    "> this is a quoted piece of text\n",
    "> said by someone very important\n",
    "```\n",
    "\n",
    "produces:\n",
    "> this is a quoted piece of text\n",
    "> said by someone very important"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "760d0e68",
   "metadata": {},
   "source": [
    "## LaTeX Equations\n",
    "\n",
    "It is possible to include LaTeX equations in Markdown cells in a Jupyter Notebook.\n",
    "\n",
    "Here is a link to a **LateX cheat sheet** if you are not familiar with it, https://wch.github.io/latexsheet/\n",
    "\n",
    "### Inline equations\n",
    "\n",
    "To include LaTeX equations inline in text, enclose the LaTeX in dollar signs.\n",
    "For example \\\\$E=mc^2\\\\$ renders as $E=mc^2$\n",
    "\n",
    "### Stand-alone equations\n",
    "\n",
    "To include a LaTeX equation on a stand-alone line, centered, enclose in double dollar signs.\n",
    "\n",
    "For example, \\\\$\\\\$ y = \\int_0^\\infty e^{-ax^2}\\\\,dx \\\\$\\\\$ renders as:\n",
    "\n",
    "$$y = \\int_0^\\infty e^{-ax^2}\\,dx$$\n",
    "\n",
    "and \\\\$\\\\$ f(x) = \\frac{x^3}{2x + 4} + \\sin{(3x)} \\\\$\\\\$ renders as:\n",
    "\n",
    "$$ f(x) = \\frac{x^3}{2x + 4} + \\sin{(3x)}$$\n",
    "\n",
    "### Using LaTeX gather, align etc.\n",
    "\n",
    "It is possible to use LaTeX gather, align etc environments in Markdown. There is an issue with using the double-dollar \\\\$\\\\$ notation as it automatically inserts `\\begin{equation}` and `\\end{equation}`. The solution is to use enclose with single dollar signs and to explicitly use the LaTeX equation environment you want.\n",
    "\n",
    "Examples:\n",
    "```markdown\n",
    "$\n",
    "\\begin{align}\n",
    "x &= (a+b)^2\\\\[1ex]\n",
    "  &= a^2 + 2ab + b^2\n",
    "\\end{align}\n",
    "$\n",
    "```\n",
    "renders as:\n",
    "\n",
    "$\n",
    "\\begin{align}\n",
    "x &= (a+b)^2\\\\[1ex]\n",
    "  &= a^2 + 2ab + b^2\n",
    "\\end{align}\n",
    "$"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "958379f9",
   "metadata": {},
   "source": [
    "## Line breaks and Rules \n",
    "\n",
    "Line breaks can be achieved with a double space between lines or inserting a `<br>` at the end of a line.\n",
    "\n",
    "Horizontal rules can be achieved with three hyphens, asterisks or underscores,\n",
    "\n",
    "e.g. the following markdown\n",
    "```markdown\n",
    "---\n",
    "```\n",
    "produces:\n",
    "\n",
    "---\n",
    "\n",
    "the horizontal rule above.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "02b29b36",
   "metadata": {},
   "source": [
    "## Code:\n",
    "\n",
    "Code may be included inline in text using single back quotes, for example \\`import numpy as np\\` produces `import numpy as np`.\n",
    "\n",
    "\n",
    "---\n",
    "\n",
    "Code blocks may be included using triple quotes:\n",
    "\n",
    "The following markdown code: <br/>\n",
    "\\`\\`\\`<br/>\n",
    "import numpy as np\n",
    "\n",
    "x = np.arange(10) <br/>\n",
    "\\`\\`\\`\n",
    "\n",
    "produces:\n",
    "\n",
    "```\n",
    "import numpy as np\n",
    "\n",
    "x = np.arange(10)\n",
    "```\n",
    "\n",
    "---\n",
    "\n",
    "If you specify that the code is a **particular language**, then for many languages you get **syntax highlighting**:\n",
    "\n",
    "The following markdown code: <br/>\n",
    "\\`\\`\\`python<br/>\n",
    "import numpy as np\n",
    "\n",
    "x = np.arange(10) <br/>\n",
    "\\`\\`\\`\n",
    "\n",
    "produces:\n",
    "\n",
    "```python\n",
    "import numpy as np\n",
    "\n",
    "x = np.arange(10)\n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e0017b02",
   "metadata": {},
   "source": [
    "<a id='Lists'></a>\n",
    "\n",
    "## Lists\n",
    "\n",
    "Ordered lists and sublists can be produced by placing numbers in front of text, examples:\n",
    "\n",
    "The following markdown:\n",
    "```markdown\n",
    "1. outer first\n",
    "2. outer second\n",
    "  1. inner first\n",
    "  2. inner second\n",
    "  3. inner third\n",
    "3. outer third\n",
    "``` \n",
    "produces\n",
    "\n",
    "1. outer first\n",
    "2. outer second\n",
    "  1. inner first\n",
    "  2. inner second\n",
    "  3. inner third\n",
    "3. outer third\n",
    "\n",
    "Unordered lists can be produced with asterix, plus signs or minus signs:\n",
    "\n",
    "```markdown\n",
    "- outer first\n",
    "- outer second\n",
    "  - inner first\n",
    "  - inner second\n",
    "  - inner third\n",
    "- outer third\n",
    "```\n",
    "\n",
    "- outer first\n",
    "- outer second\n",
    "  - inner first\n",
    "  - inner second\n",
    "  - inner third\n",
    "- outer third\n",
    "\n",
    "\n",
    "The ordered and unordered can be mixed:\n",
    "\n",
    "```markdown\n",
    "1. outer first\n",
    "2. outer second\n",
    "  - inner first\n",
    "  - inner second\n",
    "  - inner third\n",
    "3. outer third\n",
    "```\n",
    "\n",
    "1. outer first\n",
    "2. outer second\n",
    "  - inner first\n",
    "  - inner second\n",
    "  - inner third\n",
    "3. outer third"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dd754b09",
   "metadata": {},
   "source": [
    "## Tables\n",
    "\n",
    "Tables are made as illustrated below and do not need to be formatted nicely to render correctly, but it is helpful! \n",
    "\n",
    "Best illustrated with an example:\n",
    "\n",
    "The following markdown:\n",
    "```markdown\n",
    "| x (m)   | T (K) | \n",
    "| --------|-------|\n",
    "| 1.0     | 293.0 |\n",
    "| 2.0     | 298.0 |\n",
    "| 3.0     | 305.0 |\n",
    "```\n",
    "\n",
    "produces:\n",
    "\n",
    "| x (m)   | T (K) | \n",
    "|---------|-------|\n",
    "| 1.0     | 293.0 |\n",
    "| 2.0     | 298.0 |\n",
    "| 3.0     | 305.0 |"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d0d261a3",
   "metadata": {},
   "source": [
    "## Links\n",
    "\n",
    "Hyperlinks and links to files etc can be included in markdown.\n",
    "\n",
    "To link to an extenal url use `[link name](url)`, e.g. `[Duck Duck Go](https://duckduckgo.com)` gives [Duck Duck Go](https://duckduckgo.com)\n",
    "\n",
    "You can also link to sections of the Jupyter notebook (as is done in this notebook) - for information see [here](https://sebastianraschka.com/Articles/2014_ipython_internal_links.html). However, the internal links to not work in GitHub-rendered documents nor in Google Colab."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "06276723",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c16de4ad",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "colab": {
   "include_colab_link": true,
   "name": "How to use markdown cells.ipynb",
   "provenance": []
  },
  "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.9.7"
  },
  "latex_envs": {
   "LaTeX_envs_menu_present": true,
   "autoclose": true,
   "autocomplete": true,
   "bibliofile": "biblio.bib",
   "cite_by": "apalike",
   "current_citInitial": 1,
   "eqLabelWithNumbers": true,
   "eqNumInitial": 1,
   "hotkeys": {
    "equation": "Ctrl-E",
    "itemize": "Ctrl-I"
   },
   "labels_anchors": false,
   "latex_user_defs": false,
   "report_style_numbering": true,
   "user_envs_cfg": false
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": true,
   "sideBar": true,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {},
   "toc_section_display": true,
   "toc_window_display": false
  },
  "varInspector": {
   "cols": {
    "lenName": 16,
    "lenType": 16,
    "lenVar": 40
   },
   "kernels_config": {
    "python": {
     "delete_cmd_postfix": "",
     "delete_cmd_prefix": "del ",
     "library": "var_list.py",
     "varRefreshCmd": "print(var_dic_list())"
    },
    "r": {
     "delete_cmd_postfix": ") ",
     "delete_cmd_prefix": "rm(",
     "library": "var_list.r",
     "varRefreshCmd": "cat(var_dic_list()) "
    }
   },
   "types_to_exclude": [
    "module",
    "function",
    "builtin_function_or_method",
    "instance",
    "_Feature"
   ],
   "window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}