Code 102, Intro to Software Development

Class 01 - Reading Notes

Basic Syntax

Overview

Nearly all Markdown applications support the basic syntax outlined in the original Markdown design document.

Headings

To create a heading, add number signs (#) in front of a word or phrase. The number of number signs you use should correspond to the heading level.

Headings are available in six different sizes, by utilizing the # symbol, with the largest using one symbol and the smallest using six.

Alternate Syntax

Alternatively, on the line below the text, add any number of == characters for heading level 1 or – characters for heading level 2.

Heading Best Practices

Markdown applications don’t agree on how to handle a missing space between the number signs (#) and the heading name. For compatibility, always put a space between the number signs and the heading name. You should also put blank lines before and after a heading for compatibility.

Paragraphs

To create paragraphs, use a blank line to separate one or more lines of text.

Paragraph Best Practices

Unless the paragraph is in a list, don’t indent paragraphs with spaces or tabs.

Line Breaks

To create a line break or new line, end a line with two or more spaces, and then type return.

Line Break Best Practices

If you were taught to type sentences with two spaces at the end, use br instead. For compatibility, do not use a backslash.

Emphasis

You can add emphasis by making text bold or italic.

Bold

To emphasize by making text bold, use two asterisks or two underscores on either side of the text.

If you need to make letters in the middle of a word bold, use asterisks for compatibility.

Italic

To emphasize by making text italic, use one asterisk or one underscore on either side of the text.

If you need to make letters in the middle of a word italic, use asterisks for compatibility.

Bold and Italic

To emphasize by making text bold and italic, use three asterisks or three underscores on either side of the text.

If you need to make letters in the middle of a word bold and italic, use asterisks for compatibility.

Blockquotes

To create a blockquote, add a ‘greater than’ > symbol in front of the text you wish to quote. If your quote has multiple paragraphs, use the > symbol on the blank lines between paragraphs.

To nest a block quote within another block quote, use two ‘greater than’ symbols >> Other elements such as headings and ordered lists can be used within a block quote.

For compatibility, put a blank line before and after block quotes

Multiple Paragraphs

Blockquotes can contain multiple paragraphs. Add a > on the blank lines between the paragraphs.

Nested Blockquotes

Blockquotes can be nested. Add a » in front of the paragraph you want to nest.

Blockquotes w/other elements

Blockquotes can contain other Markdown formatted elements. Not all elements can be used — you’ll need to experiment to see which ones work.

Blockquotes Best Practices

For compatibility, put blank lines before and after blockquotes.

Lists

You can organize items into ordered and unordered lists.

Ordered Lists

To present items in an ordered list, add items on separate lines, preceded by a number and a period. Any number can be used, but the first number must be 1!

For compatibility, do not use parentheses for list items.

Unodered Lists

To present items in an unordered list, add items on separate lines, preceded by a dash -, asterisk *, or plus sign +. These symbols are referred to as ‘delimiters’.

For compatibility, do not combine delimiters in a single list.

Adding Elements in Lists

Indent added elements by adding four spaces or one tab. To add code blocks, indent eight spaces or two tabs.

Code

Code blocks are normally indented four spaces or one tab. When they’re in a list, indent them eight spaces or two tabs.

To denote a word or phrase as code, enclose it in backticks.

Escaping Backticks

If your text already includes backticks, use double backticks (``).

Code Blocks

To create code blocks, indent every line of the block by at least four spaces or one tab.

Horizontal Rules

To create a horizontal line to separate text, use three asterisks ***, dashes ---, or underscores ___.

Horizontal Rule Best Practices

For compatibility, put a blank line before and after each horizontal rule.

Links

To create a link, enclose the text for the link in brackets [], followed by the URL in parentheses ().

Adding Titles

To add a title to a link (the small box with text that shows when you hover over the text), add your title text in quotation marks after the URL, but still within the parentheses.

URLs and Email Addresses

To link a URL without text, or link an email address, use angle brackets <>.

Formatting Links

Links can be formatted as bold, italic, or code, just like text.

Reference Style Links

This style of link, makes URLs easier to read in markdown. The first segment (which is easily readable), makes reference to the second segment, the longer URL, which can be embedded anywhere in the markdown.

First segment: [URL Reference][label]
Second segment: [label]: "Optional Title"

Links Best Practices

For compatibility, use %20 in place of any spaces in the URL text.

Images

To add an image, use an exclamation mark in parentheses, followed by alt text in brackets, then the image location in parentheses. Optionally, add text in quotation marks for a title.

Linking Images

To add a link to the image, enclose the image markdown in brackets, then add the link in parentheses.

Escaping Characters

Escaping characters refers to displaying characters that are assumed to be part of the markup. Use a backslash to escape a character.

Characters you can escape

The following may be escaped: `*{}<>#+-.!

HTML

Sometimes, markdown applications allow the use of HTML tags.

HTML Best Practices

Check your markdown application’s documentation!

https://chrisjohnston1986.github.io/reading-notes/102/102class01reading