GeorgeHernandez/markdownNotes.md

## markdownNotes.md

      
    Raw
  

              markdownNotes.md
            
          
    Markdown Notes


Summary: Notes on Markdown, a lightweight markup language that converts into HTML. N.B. DO NOT edit this files in an autoformatting setting because it has many purposeful "exceptions".
Authors: George Hernandez
Audience: Public

Block HTML

Headers (hn)

Prefix with 1..6 pound signs (#). E.g.
# h1

## h2

### h3

#### h4

##### h5

###### h6
becomes:
h1

h2

h3

h4

h5

h6

For h1 and h2, you can also use a syntax of underlining with = or - respectively. E.g.
h1
==

h2
--
becomes:
h1

h2

Horizontal rules (hr)

Put several *, -, or _ on their own line, i.e. prefixed and suffixed by \r. E.g.
foo

---

bar
becomes:
foo

bar
Paragraphs (p)

Paragraphs are followed by 2 newlines. E.g.
Sentence #1a of Paragraph #1 is followed by 2 newlines.

Sentence #2a of Paragraph #2.
Sentence #2b of Paragraph #2.
becomes:
Sentence #1a of Paragraph #1 is followed by 2 newlines.
Sentence #2a of Paragraph #2.
Sentence #2b of Paragraph #2.
Breaks (br)

A break within a paragraph is done several ways:

1 backslash (\) at the end of the line.
1 literal <br> at the end of the line. Avoid since some systems abhor inline HTML.
2 spaces (  ) at the end of the line. Avoid since some systems auto-delete trailing whitespace.
1 newline (instead of 2) at the end of the line. Avoid since this doesn't work in some systems.

E.g.
This line ends in 1 backslash (`\`)\
The next line

This line ends in 1 literal `<br>`<br>
The next line

This line ends in 2 spaces (`  `)  
The next line

This line ends in 1 newline
The next line
becomes:
This line ends in 1 backslash (\)

The next line
This line ends in 1 literal <br>

The next line
This line ends in 2 spaces (  )
The next line
This line ends in 1 newline
The next line
Block quotes (blockquote)

Block quotes are prefixed with a >. E.g.
A blockquote followed by 2 returns makes 2 blockquotes.

> Blockquote #1.

> Blockquote #2.

Usually you want regular text between blockquotes to make it explicit.

> Blockquote #3.

If 2 sequential blockquotes are separated by 1 return, then they are **automatically joined** into 1 blockquote.

> Blockquote #4.
> This is still part of Blockquote #4.
> This very long line is also part of Blockquote #4. Yes, it is a very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very long line.

If you want a visual blank line within a blockquote, then the prefix the blank line with a `>`.

> Blockquote #5.
>
> This is still part of Blockquote #5

A blockquote can have a nested quote.

> Blockquote #6.
>
> > Blockquote #6a is nexted within Blockquote #6.
> > Will line A belong to Blockquote #6 or #6a?
> Will line B belong to Blockquote #6 or #6a?
>
> Will line C belong to Blockquote #6 or #6a?
becomes:
A blockquote followed by 2 returns makes 2 blockquotes.

Blockquote #1.


Blockquote #2.

Usually you want regular text between blockquotes to make it explicit.

Blockquote #3.

If 2 sequential blockquotes are separated by 1 return, then they are automatically joined into 1 blockquote.

Blockquote #4.
This is still part of Blockquote #4.
This very long line is also part of Blockquote #4. Yes, it is a very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very very long line.

If you want a visual blank line within a blockquote, then the prefix the blank line with a >.

Blockquote #5.
This is still part of Blockquote #5

A blockquote can have a nested quote.

Blockquote #6.

Blockquote #6a is nexted within Blockquote #6.
Will line A belong to Blockquote #6 or #6a?
Will line B belong to Blockquote #6 or #6a?

Will line C belong to Blockquote #6 or #6a?

Preformatted Code (pre)

Preformatted code is prefixed with 4 spaces (    ). E.g.
    `pre` via 4 spaces.
becomes:
`pre` via 4 spaces

Alternatively "fencing" tags the block with 3 back ticks (```). E.g.
```
`pre` via tagging with 3 back ticks (aka fencing)
```

becomes:
`pre` via tagging with 3 back ticks (aka fencing)

With fencing, you can suffix the opening backticks with the language used. E.g.
```javascript
let s = "JavaScript syntax highlighting";
alert(s);
```
becomes:
let s = "JavaScript syntax highlighting";
alert(s);
Lists (ul, ol, li)

Unordered lists, ordered lists, and list items with a simple syntax. E.g.
- Nest lists with indentation.

  - Use a Dash, but supposedly `*` and `+` work too.
  - This list item
    breaks via `\r` (and may not work)
  - This list item\
    break via `\r\`
  - This list item

    breaks via `\r\r`

  - List item
    > with a blockquote
  - List item

    ```html
    with PRE
    ```

1. Make numbered lists
1. via any integer and a period.
   1. Short items don't need a list
   1. as much as long items do.
      1971\. The backslash escapes and avoids a list item.
becomes:


Nest lists with indentation.


Use a Dash, but supposedly * and + work too.


This list item
breaks via \r


This list item

break via \r\


This list item
breaks via \r\r


List item

with a blockquote


List item
with PRE


Make numbered lists
via any integer and a period.

Short items don't need a list
as much as long items do.
1971. The backslash escapes and avoids a list item.


Github's Markdown allows TODO lists. E.g.
- [ ] TODO
- [/] Doing (not implemented)
- [\] Doing (not implemented)
- [x] Done
becomes:

 TODO
[/] Doing (not implemented)
[] Doing (not implemented)
 Done

Span HTML

Basic spans (em, strong, code, s)

The em tag is made with single asterisks (preferred because underscores are more often parts of words) or single underscores, and is usually rendered as italics. E.g. *foo* becomes foo and _foo_ becomes foo.
The strong tag is made with double asterisks (preferred because underscores are more often parts of words) or double underscores. E.g. **foo** becomes foo and __foo__ becomes foo.
To use both em and strong tripple asterisks (preferred because underscores are more often parts of words) or triple underscores, and is usually rendered as bold. E.g. ***foo*** becomes foo and ___foo___ becomes foo.
The code tag is made with single backticks, and is usually rendered as monospace. E.g. `foo` becomes foo. To display multiple backticks, then enclose with even more backticks! E.g. ````enclose code with 3 backticks (```) with 4 backticks```` becomes enclose code with 3 backticks (```) with 4 backticks.
The strike tag is HTML 5 obsolete in favor of the s tag or the ins and del tag pair. In Markdowns the s tag is made with double tildes, and is usually rendered as a strikethrough. E.g ~~foo~~ become foo.
Links (a)


URL #1. E.g. http://example.com & foo@example.com become http://example.com & foo@example.com.
URL #2. E.g. <http://example.com> & <foo@example.com> become http://example.com & foo@example.com.
Alt, URL. E.g. [example](https://example.com) becomes example.
Alt, URL, title. E.g. [example](https://example.com "tooltip") becomes example.
Local relative link. E.g. [About](about.htm) becomes About.
Format links. E.g.

**[example](https://example.com)** becomes example
_[example](https://example.com)_ becomes example
[`example`](https://example.com) becomes example


Encoding. It safer to URL encode some characters in URLs. E.g.

[foo](https://example/my%20foo) becomes foo
[bar](https://example/identity_%28id%29) becomes bar
<a href="https://example/identity_(id)">bar</a> becomes bar


A reference-style link has 2 parts:

The URL is refrenced by an ID that is specified anywhere on the page but often at the end of the document. E.g.

[1]:  https://example.com/1
[2]: <https://example.com/2>
[3]:  https://example.com/3 "tooltip"
[4]: <https://example.com/4> "tooltip"


The ID can be used 1..N times on the page. E.g.

[One][1] and [Two] [2] are good but [Two][2] is better


Images (img)

Alt, URL. E.g.
![Google](https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png)
becomes

Alt, URL, title. E.g.
![Google](https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png "rocks")
becomes

Alt, URL, title, href. E.g.
[![Google](https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png "rocks")](https://google.com)
becomes

Inline HTML

The characters &, <, and > are usually automatically escaped. E.g.
AT&T becomes AT&amp;T
7 < 8 becomes 7 &lt; 8
8 > 7 becomes 8 &gt; 7
Certain characters can be escaped with a preceding backslash (\) to preserve the literal display of a character instead of its special Markdown meaning. This applies to the following characters:
\  backslash
`  backtick
*  asterisk
_  underscore
{} curly braces
[] square brackets
() parentheses
#  hash mark
>  greater than
+  plus sign
-  minus sign (hyphen)
.  dot
!  exclamation mark

Tables (table, tr, th, td)

Markdown has syntax for implementing simpler tables. E.g.
| TH cells      |         are          | bold & centered by default |
| ------------- | :------------------: | -------------------------: |
| col 1 is      |     left-aligned     |                  some text |
| col 2 is      |       centered       |                        $69 |
| col 3 is      |    right-aligned     |                     $69420 |
| col 4 is      |    right-aligned     |                       $420 |
| zebra stripes |         are          |                  automated |
| *em*          |      **strong**      |                     `code` |
|               | alas no joined cells |
becomes:


TH cells
are
bold & centered by default


col 1 is
left-aligned
some text


col 2 is
centered
$69


col 3 is
right-aligned
$69420


col 4 is
right-aligned
$420


zebra stripes
are
automated


em
strong
code


alas no joined cells


Alternatively you can try raw HTML. E.g.
<table>
  <tr>
    <th>My header</th>
  </tr>
  <tr>
    <td>Table HTML MAY work in Markdown</td>
  </tr>
</table>
MAY become:

    
        My header
    
    
        Table HTML MAY work in Markdown
    

Etc

Markdown does not cover all HTML.

To do subscripts, use raw HTML. E.g. H<sub>2</sub>O is water becomes H₂O is water. Alternatively you could use naturally superscripted characters. E.g. H₂O is water becomes H₂O is water.
To do superscripts, use raw HTML. E.g. 3<sup>2</sup> = 9 becomes 3² = 9. Alternatively you could use naturally superscripted characters. E.g. 3² = 9 becomes 3² = 9.

Glossaries

Raw HTML may be used for glossaries. E.g.
<dl>
  <dt>term</dt>
  <dd>definition</dd>
  <dt>term 2</dt>
  <dd>definition 2</dd>
</dl>
MAY become:

  term
  definition
  term 2
  definition 2

Links


http://en.wikipedia.org/wiki/Markdown.
"Markdown is a plain text formatting syntax[5] designed so that it can be converted to HTML and many other formats[6] using a tool by the same name. Markdown is often used to format readme files, for writing messages in online discussion forums, and to create rich text using a plain text editor."
Markdown: Syntax. By John Gruber, the creator of Markdown.
Markup Online.
https://help.github.com/articles/markdown-basics/.
https://bitbucket.org/tutorials/markdowndemo.
https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet.
https://talk.commonmark.org/t/we-should-abandon-indented-code-blocks/182. Yes!
http://commonmark.org/
https://www.markdownguide.org/basic-syntax/
https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/
Use Markdown in Google Docs, Slides, & Drawings. Since around 2022-04. Italics, Bold, Italics & Bold, Strikethrough (enclose with - instead of ~~), Links, & Headings. Google has already been converting -  or *  to a bullet list item.
TH cells	are	bold & centered by default
col 1 is	left-aligned	some text
col 2 is	centered	$69
col 3 is	right-aligned	$69420
col 4 is	right-aligned	$420
zebra stripes	are	automated
em	strong	`code`
	alas no joined cells