Basic Markdown

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.

1. Paragraphs
2. Formatting
3. Escaping
4. Headings
5. Links / Hyperlinks
   1. Hyperlinked Words
   2. Autolinked URLs
6. Images
7. Lists
8. Separators
9. Hard Returns
10. Blocks
    1. Plain
    2. Code Fences
       1. Don’t Forget the Blank Lines
       2. Exception for Markdown
11. Blockquotes
12. Comments
13. FAQ
    1. Why Not Use Tables?
    2. What About GitHub Tables?
    3. Can’t I Use Reference Links at the Bottom?
    4. What About _ Underscore?
    5. [Can’t I Just Use http for Links?]

Paragraphs

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

To move paragraphs around all you have to do is copy that single line (yy or dd in Vi). Single-line paragraphs always properly wrap no matter what editor you are using or its width. Don’t forget to put one blank line before and after each paragraph to separate it from the rest. Paragraphs frequently contain formatting.

Also note that this does not apply to the YAML front-matter at the top of a Markdown document. This is explained more in Pandoc Light Markdown but just know that limiting text blocks to 72 — small enough for allow for line numbering and a gutter on the left-side required by Vim and other editors — columns is wise for such things since YAML depends so heavily on clean left-side indentation.

:::

  ## Example of Good Wrapping

  This is a rather long paragraph that extends well beyond the 80 characters of most terminals and in the old days would be chopped into smaller individual lines rather than this big long huge line.
  

Although every Markdown tool allows multiple lines to be grouped into a single paragraph so long as a they are followed by a blank line this practice is rather bad when editing those same files with editor or terminal or tmux pane widths that are less than the line length. They are completely unreadable. Stay safe, just use single long lines. All modern (and even most ancient editors) support auto-wrapping the line in the terminal rather than effectively hard wrapping it in the display.

  ## Example of Bad Wrapping

  This is a rather long paragraph that has been chopped forcefully into
  individual likes of less than 80 characters each. While this might look
  reasoably well on a standard 80 character terminal it looks horrible when in
  modern TMUX panes that might contain far less than that and wastes available
  characters when more are available.
  

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 (*) 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. 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 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

Don’t Forget the Blank Lines

Even though all forms of Markdown support code fences that immediately contain content without a blank line after the opening fence post or before the final fence post you really should always add one and adjust your rendering styles appropriately. This is because without that initial blank browsers like FireFox that correctly respect whitespace as a DOM node will show your code incorrectly in a pre-formatted style. Plus the separation makes your knowledge source much easier to read and search.

  Don't do this:

  ```js
  console.log('Hello')
  ```

  Do this instead:

  ```js

  console.log('Hello')

  ```
  

Exception for Markdown

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.