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.