Introduction to Markdown#

What is Markdown?#

Markdown is a lightweight markup language, where you can use simple formatting elements and the LaTeX math environments to generate elegant-looking notes that can be converted to HTML or pdf. Markdown is different than a typical text editor because it does not show the formatting on the fly (i.e., a WSIWYG editor). Instead it allows for simple text commands to stand for formatting elements and implements them on “compilation”. However, more complex markup from HTML can be used too.

Why Use Markdown?#

There are several reasons to use markdown, which make it the more convenient choice over a WSIWYG editor (e.g., MS Word). For example,

  • Markdown can be used for everything (e.g., websites, documents, notes, books, etc.).

  • Markdown is how we include standard text alongside code within Jupyter notebooks. Jupyter notebooks use cells like Mathematica or Matlab, where the cells can contain python or Markdown. This documentation is developed in a Jupyter notebook with Markdown.

  • Markdown is platform independent. PC, Linux, and Mac users can finally live in harmony!

  • Markdown allows for LaTeX in-line math commands (e.g., \(y=mx+b\) or \(\mathbf{F} = m \frac{d^2\mathbf{x}}{dt^2}\)), which can be extremely useful for writing up class notes or homework assignments.

  • Markdown makes linking to other webpages easy.

Visit the Markdown Guide’s getting started page for more details.

Basic Syntax#

Section Headings#

To create a section heading, use the # symbol as the first character on a line, followed by a space, and then the word (or phrase) that you need for the section heading. To create sublevels for the section heading, just add another # sign that corresponds to the level. For example, the section headings rendered above are given in Markdown as,

# Basic Syntax

## Section Headings

Heading Best Practices#

  • Include a space between the # and the words for the section heading.

  • Put blank lines before and after a heading to ensure compatibility.

Paragraphs and Line Breaks#

Paragraphs are rendered as blocks of text that are separated by a blank line. The HTML paragraph open tag <p> can also be used, but it needs to have the paragraph close tag </p> as well.

To create a line break, end a line with two or more spaces followed by a return. The HTML line break tag <br> can be used for a single line break.

Paragraph and Line Break Best Practices#

  • Keep your lines left-aligned.

  • Don’t indent paragraphs with spaces or tabs. If you need to indent a paragraph use the HTML non-breaking space &nbsp; four times to mimic an tab indent.

  • Use either two trailing whites spaces or the <br> HTML tag at the end of a line for the broadest compatibility.

Font Typesetting#

Sometimes you might want to add emphasis so that a particular line or phrase pops out. Markdown uses a single * before and after a word (or phrase) to indicate italics and a ** to indicate bold. If the text is really important with both bold and italics, then a *** can be used.

Font Typesetting Best Practices#

  • Single, double, and triple underscores can be used for italics, bold, and bold-italics, respectively. But compatibility not all Markdown applications agree on this convention.

Blockquotes#

Blockquotes are sometimes necessary to emphasize a particular section or give it a distinctive look. The > character at the beginning of a line indicates a blockquote, where the number > characters corresponds to the nesting of the blockquote (i.e., like the section headings). Blockqoutes can contain other formatted elements (e.g., italics or bold).

A single blockquote can be good to set some text apart.

A subsection of a blockquote is just as easy.

Blockquotes Best Practices#

  • For compatibility, put blank lines before and after blockquotes.

Lists#

To create items in a list, you can use either numbers or bullets. For numbers, simply start a line with a number, followed by a period, then a space, and finally the text item. Bullets follow a similar syntax, but with - and a space.

  1. First layer

    1.1 Use 4 spaces for the second layer

  2. Second item

  • First layer

    • Second layer

      • Third layer

Lists Best Practices#

  • Use number dot (1.) format for the best compatibility.

  • Other characters (* or +) can be used for bullet lists. Pick one and be consistent.

Math Environment with LaTeX#

A LaTeX math guide for undergrads is available from the Mathematics Department of Saint Michael’s College, VT. This guide can be useful as a quick reference.

LaTeX math commands can be rendered with a single $ in the in-line format that you may already know. To write math equations on a separate line (centered), use $$ instead.

  • Similar to other best practices, be sure to have 1 blank line before and after the equation.

  • Also make sure that you end your equation with an appropriate $ character.

Adding images to Google Colab Markdown cells#

Google Colab does not recognize images stored locally.  If you want the full explanation and directions, see this forum from stackoverflow

https://stackoverflow.com/questions/50670920/how-to-insert-an-inline-image-in-google-colaboratory-from-google-drive/50672083#50672083

If you want to load an image into your Markdown cell in Google Colab, you need to do the following:

  • upload your image to your Google Drive

  • right click on the file and select Get Link

  • Change the permissions to allow anyone with a link to view the file

  • Copy the link

  • Then you can use the standard way to add an image to Markdown (i.e., ![image text](image_url)). But you have to use https://drive.google.com/uc?export=view&id= with the image id from your image link to make the image_url

galaxy_wallpaper.jpg is in my Google Drive with permissions enabled

https://drive.google.com/file/d/image_id/view?usp=sharing is the shared file link

https://drive.google.com/uc?export=view&id=imageid is the image_url for Markdown in Google Colab

Here is another workaround using the Python code cell.  It assumes that you have uploaded your file already.  Just replace “galaxy.jpg” with your filename, and adjust as needed.

from IPython.display import Image Image(‘galaxy.jpg’,width=400, height=400)