Basic Markdown

Priority on Simplicity and Compatibility

Here is quick overview that you can complete in 20 minutes covering the most basic, compatible Markdown everyone should learn. The priority is on simplicity and maximum compatibility. It allows your content to be used everywhere. There is no more ubiquitous form of knowledge storage.

Paragraphs

A paragraph is either a long single line of text followed by a blank line or multiple lines one after another. You pick but it’s a good idea to use one consistently throughout the same document or knowledge base.

Inline Formatting

One star for italics:

one star for *italics* 

Two stars for bold:

two stars for **bold**

Three stars for bold italics:

three stars for ***bold italics***

Backticks for code also known as monospaced:

backticks for `monospaced`

[What about _ underscore?]

Escaping

Any time you don’t want, say, a star (*) or a dollar sign ($) to be recognized by the Markdown parser just put a backslash in front of it. This goes for all the other special symbols used in Markdown. In fact, you can put a backslash (\) in front of any character whatsoever in Pandoc Markdown to cause it to be used as is.

Headings

Headings (often incorrectly called headers) begin with 1-6 hashtags (#) followed by a space and then the title text followed by a single blank line.

# Level One

  Paragraphs and such here.

  ## Level Two

  Paragraphs and such here.

Formatting is allowed in headings but can be problematic with some renderers. Avoid if you can.

Links / Hyperlinks

Hyperlinks (stuff you click on) come in three basic forms:

1. Words
2. Raw URLs
3. Images

Hyperlinked Words

The most common link in Markdown is just words you can click on that take you to local places or external sites. The web address must be either pointing to a remote site or so something on the same site that document is on.

Here is a [link to rwx.gg](https://rwx.gg).

Autolinked Raw URLs

Sometimes you want to show the full web address.

Here is URL to <https://rwx.gg/md> that will appear in full.

[Can’t I just use http for links?]

This also works with other link types besides http. (Yes, there are several other URL schemas.)

Mail me at <mailto:rwx@robs.io>.  
  Phone me at <tel:555-555-5555>

Images

Images are just links with an exclamation point in front. Make sure to put a blank line before and after any image for maximum compatibility. Inline images are not widely supported and mess up other formatting in almost all cases.

![gnome](/assets/img/mr-rob-gnome.jpg)

Images can also be used as links.

[![RWXROB](/assets/img/mr-rob-gnome.jpg)](https://rwxrob.live)

Lists

Simple lists are supported by pretty much everything. Put the list items one to a line. Make sure to put a blank line after the list.

Use stars followed by spaces (*) for bulleted (unordered) lists:

* some
  * thing
  * here

• some
• thing
• here

Use the number one followed by a period and a space (1.) for numbered (ordered) lists:

1. HTML 
  1. CSS
  1. JavaScript
  1. Go
  1. Bash

1. HTML
2. CSS
3. JavaScript
4. Go
5. Bash

Always use 1. so that if you change the order you do not have to renumber the source itself. It will automatically change the number order when rendered.

Separators

Also called “horizontal rule.” These just break up the page usually with a horizontal line.

----
  

Here comes an example of a separator.

---

Use four dashes for consistency even though there are dozens of ways to indicate separation (some of which allow stars to be used as well). This consistency allows you to easily find your separators and keeps them from being confused with YAML markers (which use three dashes) and inline formatting (which uses stars *).

Hard Returns

Hard returns are a way of starting a new line within a given paragraph. Type two spaces (␣␣) followed by the line return.

Roses are red␣␣
  Violets are blue

Rose are red
Violets are blue

Roses are red↵
  Violets are blue

Blocks

Blocks separate text or code from the document usually as a box. There are two main block types to remember: plain (preformatted, as-is) blocks and code fences. Both use three backticks to “fence off” the text or code.

Plain

When you just want the text to appear exactly as it is just use the triple-backtick fence posts.

```
      Roses are red
      Violets are violet
  ```

    Roses are red
      Violets are violet

Code Fences

Code blocks are perhaps the single biggest reason to use markdown for all your tech writing and note taking. If you want syntax highlighting in your notes you get it for free. This provides very high-quality publications very easily

When you want to add syntax highlighting or otherwise indicate how the text should be handle provide an information tag immediately following the first triple-backtick fence, so for JavaScript it would be:

```js
  console.log('hello world')
  ```

Note that color syntax highlighting here has disabled because it can distract from equal focus on everything being displayed and creates unreadable text for those challenged with distinguishing different colors — especially in educational settings.

console.log('hello world')

Although there are other ways to write blocks, using triple-backtick fences is the most consistent way to do them all. This allows quickly finding your blocks when editing as well as filtering them out easily with scripting or simple parsing. It is also the most widely supported. Discord, for example, only supports this format of code fence.

Here is a short list of supported language tags:

Tag	Language
md	Markdown
json	JSON
js	JavaScript
html	HTML
css	CSS
sh	Shell or Bash
go	Go (golang)

Exception for Markdown

Skip this if you are just beginning.

In the single exceptional case where you need your block to contain markdown code you should use three or four tildes (~~~markdown or ~~~~markdown). Again, this consistency allows you to filter out blocks from simple scripts that examine each line which can be useful for coding keyword searches and such.

  ~~~markdown

  Here is *some* markdown.

  ```js

  console.log('hello example')

  ```

  ~~~
  

  Here is *some* markdown.

  ```js

  console.log('hello example')

  ```
  

There are literally an infinite number of possible ways to indicate a block supported by the original and most derived Markdown parsers. Just stick with these two options. Consistency is far more important than artistic expression. Blocks are particularly important to keep consistent because you will frequently want to simply strip them out for keyword searches and such. Following these suggestions makes this trivial even from simple shell scripts.

Blockquotes

Blockquotes are for quotations and only quotations. Avoid the temptation to use them for anything else because if you do you can semantically identify all the actual quotes in your content.

Begin each line of the block with a greater-than sign (right angle-bracket).

Usually you will just have a single paragraph:

> "One of the painful things about our time is that those who feel
  > certainty are stupid, and those with any imagination and understanding
  > are filled with doubt and indecision." (Bertrand Russell)

“One of the painful things about our time is that those who feel certainty are stupid, and those with any imagination and understanding are filled with doubt and indecision.” (Bertrand Russell)

In the rare case that your quotation expands beyond a single line make sure to join separate paragraphs with a blank line that is also included:

> This is the first part of the quote.
  >
  > Here is the second part.

This is the first part of the quote.

Here is the second part.

Comments

Comments are just simple HTML comments, which were inherited from SGML dating back decades.

<!-- This is a comment -->

  This is a Markdown paragraph with another <!-- another --> comment in it.

This is a Markdown paragraph with another comment in it.

Even though you should seriously avoid making your Markdown HTML dependent by including HTML as the original Markdown allowed, comments are a fair exception to this because no Markdown has any other syntax for indicating comments and every Markdown parser engines supports them.