Stack Tests
0   

Introduction

Markdown is a plain text syntax that allows to layout structured documents while preserving (to a certain extent) source code compatibility. Markdown stands between rich text notes and more complex formats, such as Web or PDF documents.

This document presents the best known features of markdown.

Syntax

Elementary syntax

The following are supported by most markdown applications.

Document structure

Heading

Headings (or sections) are created by insterting one or several hashtags # at the beginning of a line, followed by a space and the text of a heading.

The number of # indicates the level of nesting. For instance #### Heading is a heading of level 4.

Paragraph

To create a new paragraph, insert a blank line.

(This is the second paragraph)

Quote

to insert a quote, just put the < character at the beginning of the line followed by a space like this > like this

Quotation with multiple paragraphs

It works just as before, except you have to insert blank lines preceded by >

We must let go of the life we have planned, so as to accept the one that is waiting for us.

Joseph Campbell

Horizontal rule

just insert a line beginning with several hyphens: ---. Separate the code text by blank lines. This is used in this document!

Lists

Unumbered lists are created by using an asterisk ( * ) followed by a space at the beginning of each line. Lists can be nested by interting 4 spaces or a tab character before the asterisk. The code

* Milk
* Bread
* Cheese
    * Roquefort
    * Camembert
* Rice

gives

  • Milk
  • Bread
  • Cheese
    • Roquefort
    • Camembert
  • Rice

Numbered lists work like unumbered lists except that you replace the asterisk with a number followed by a dot. The code

1. Milk
1. Bread
1. Cheese
    1. Roquefort
    1. Camembert
1. Rice

gives

  1. Milk
  2. Bread
  3. Cheese
    1. Roquefort
    2. Camembert
  4. Rice

Lists can contain list markdown elements. Here is a list of links (see section below about links)

The code is

* [Joplin](https://joplinapp.org/)
* [Marked 2 - Smarter tools for smarter writers](https://marked2app.com/)

Styling

Description Markdown code Output
Bold text **Bold** Bold
Italic *Italic* Italic
Bold Italic ***Important*** Important
Code  This is `some code`| This is some code

This is how the link to the Joplin home page was coded [Joplin](https://joplinapp.org/) In the two brackets at the beginning is the text that will be displayed. Between the two parentheses is the actual web address.

You can add a tooltip in the following way: [Joplin](https://joplinapp.org/ "An awesome Markdown editor") gives Joplin (Hover a few seconds over the link to see the tooltip) You can also style your links: [*Joplin*](https://joplinapp.org/ "An awesome Markdown editor") gives Joplin

For email, the following code [email me](mailto:me@domain.com) gives email me

You can create quick links by putting the link between < and >.

<https://joplinapp.org> gives https://joplinapp.org <me@domain.com> gives me@domain.com

Images

Images cannot be stored inside a Markdown text file. This means that the image must be stored elsewhere. This why the syntax is the same for a web link, with the difference that an exclamation mark ! is just before the image link. The code ![Alfred E. Neuman](https://dsc.cloud/45a53a/Like-Mad/Like-Mad.jpg) displays the following image:

Alfred E. Neuman

The text inside the bracket is an alternative text description of the image, which is useful when the link to the image does not work.

Not only can you display an image, you can also make it a link. To do so you enclose the image inside brackets (as if it was the text of a link) and append the address of the link between parentheses. Using the code [![Joplin](https://dsc.cloud/45a53a/Joplin-2x/Joplin-2x.png)](https://joplinapp.org) we generate an image with a link to the Joplin site (I love Joplin!)

Joplin

Extended syntax

Extensions of the markdown syntax which are commonly used in advanced markdown editors are described here.

Special characters

As in most languages, Markdown has its own reserved characters that you cannot simply display in the code output. These characters are

  • \
  • `
  • *
  • _
  • { and }
  • [ and ]
  • #
  • +
  • -
  • . (dot)
  • !
  • | (pipe)

To display them, you have to put a backslash \ before the character. For instance, to display an asterisk character, the code is \* .

Tables

Syntax

The table that describe the syntax for Markdown text styling was obtained by using the following markdown code:

| Description | Markdown code | Output |
| ---------- | :--------------: | ------ |
| Bold text | `**Bold**`| **Bold** |
| Italic | `*Italic*`| *Italic* |
| Bold Italic | `***Important***`| ***Important*** |
| Code | ``This is `some code` ``| This is `some code` |

Observe the use of the tick `character to create embedded code in the text. The double tick `` is used to embed markdown code that precisely contains the tick character.

Alignment

Using colons : is the separating line created by the hyphens - characters controls the alignment of the text in the corresponding:

  • for one : at the left the column is left justified (default)
  • for one : at the right the column is right justified
  • for a : at each side of the hyphens, the column is centered justified (see second colum in the example above).

Formatting Text in Tables

You can format the text within tables. For example, you can add links, code (words or phrases in backticks ( ` ) only, not code blocks (see section below)), and emphasis.

You cannot add headings, blockquotes, lists, horizontal rules, images, or HTML tags.

Fenced Code Blocks

To embed blocks of code in markdown, you just have to put before and after the markdown code a line with the triple tick ( ``` ) of three tildes ( ~~~ ). This is how the code of the styling table was exhibited in the previous section. Here is an example

```
This is my markdown code
```

This code display was itself coded using triple tildes!

Footnotes

To create a footnote reference, add a caret and an identifier inside brackets: [^identifier] . Here is some text with a footnote link1. Whatever the identifier, it will be replaced by numerals in the display. The text of the footnote can be placed anywhere, it will always be placed at the end of the display. The code for the footnote content is [^identifier]: the footnote text . You copy the footnote link code and appends it with a colon and then the footnote text.

You can create footnotes with multiple paragraphs in the content by indenting the footnote text2. Here is the code for the second footnote text:

[^multi]: This footnote has multiple paragraphs

    Labore sed sequi dolore et ratione ipsa odio sed numquam repellat dignissimos fugit.

    omnis dignissimos dolores molestiae

You may observe on some devices the presence of a horizontal scrollbar in the previous code: this is because code text cannnot be wrapped.

Definition Lists

You can use "definitions" by putting a colon followed by a space at the beginning of the text: `: This is the definition of the first term.` .

First Term : This is the definition of the first term.

Second Term : This is one definition of the second term. : This is another definition of the second term3

Strikethrough

Using double tilde ~~ delimiters you can create the following text style:

The following text is invalid.

The code for this is The following text is ~~invalid~~.

Task Lists

To add a task list, begin your lines with a hyphen - followed by a pair of brackets. If a space is inside the brackets [ ] , the checkbox is unmarked. If an x is inside the brackets [x] , the checkbox is marked. Here is an example:

  • Write the press release
  • Update the website
  • Contact the media

In Joplin, marking or unmarking the checkboxes in the preview is directly reflected into the source code4 .

Emoji

Simply paste the emoji in the source to have it displayed in the output. An example follows:

Go to 📙 Emojipedia — 😃 Home of Emoji Meanings 💁👌🎍😍 to learn about emojis. Here is a sample list of emojis:

  • happy face 😀
  • poop 💩

You can also use emoji shortcodes: the code :joy: gives 😂

LaTeX

Some markdown processers (like Joplin) render LaTeX code. To display an equation, use the double dollar $$ delimiter. To render Maths inside text (aka LR mode), use single dollar $ delimeters. Here is an example:

Let us display an differential equation in integral form:

\(x(t)=x_{0}+\int_{0}^{t}f(x(s))ds\)

Now let us put it into text by using the more compact differential form \(\frac{dx}{dt}=f(x)\;\;x(0)=x_{0}\).

The source code is below (using the "LATEX" language specification for syntax coloring):

Let us display an differential equation in integral form:

\(x(t)=x_{0}+\int_{0}^{t}f(x(s))ds\)

Now let us put it into text by using the more compact differential form  \(frac{dx}{dt}=f(x)\;\;x(0)=x_{0}\).

Internally, Joplin uses the KaTeX engine.

Table of contents

The code [toc] inserts a table of contents.

Highlight text

This is highlighted text.

The code is 

This is ==highlighted== text.

Typography

Special characters are rendered by putting a code inside parentheses. Here is a short list:

  • © is obtained with (c)
  • ® is obtained with (R)
  • ™ is obtained with (TM)

Indices and exponents

The tilde ~ delimiter encloses an index. X~1~ yields X1.

The hat ^ delimiter encloses an exponent. X^2^ yields X2.

Markdown Apps on the Mac

Some of these also have versions for several platforms, generally with syncing abilities.

Note taking apps

These apps manage a library of markdown notes

Editors

Most of them also have export capabilities.

Exporters

These applications allow you to preview markdown files and export them to various formats

My choice

I recommend the use of Joplin, which is a free, open source, markdown editor. It runs on Windows, macOS, Linux, Android and iOS. Joplin notes can be synced through Dropbox and OneDrive.

For a small monthly fee, you can have access to Joplin Cloud. It features

  • fast cloud syncing of Joplin notes
  • hosting of published notes (with a sharable link on the web)
  • a convenient clipper extension for Chrome compatible browsers.
  • published notes are automatically synced with your local Joplin notes.
  • Joplin cloud users can share notebooks between them

Plugins for Joplin are also available.

Linking with Hookmark

Hookmark is a powerful tool for creating links between documents on the Mac. It is also available on Setapp.

How does this fit into Markdown? Well, when you are working on a document, invoke the Hookmark context window and you will obtain something like this:

Hook window

Hit Command-M and paste the code into a markdown editor like Joplin. The most basic usage is for storing Web links. But you can have links to files, mails, etc

For a full list of supported Mac applications, see Linkable Mac Apps – Hook. I highly recommend this tool!

  1. My first footnote ↩

  2. This footnote has multiple paragraphs

    Labore sed sequi dolore et ratione ipsa odio sed numquam repellat dignissimos fugit.

    omnis dignissimos dolores molestiae ↩

  3. in the web version of the markdown source of this page, the definition styling is not obvious. However the corresponding HTML code is present. ↩

  4. In the web page, the marking action is performed, but does not affect the code (if you refresh the page, the previous state is restored) ↩