How to write notes using Markdown
Markdown is a widely used, almost standard way of writing human readable text-only content that can be easily formatted by machines (like blog engines or like Metanota).
The first resource to be checked by anyone wanting to know more it is John Gruber’s `Daring Fireball` web site here <http://daringfireball.net/projects/markdown>
# Highlighting vs formatting
Usually, blog engines or similar Markdown formatters will translate the Markdown formatted input text into HTML or otherwise format it for display by stripping and interpreting Markdown’s „tags“. This behavior is very well suited for web sites or publishing, were access to the original text is not immediately needed by the reader .
From a note taking app perspective (read Metanota) the original Markdown formatted text should be available and editable at any moment. For this reason Metanota is using a different approach : it is doing real time Markdown _highlighting_ without stripping original formatting elements. They need to remain in place for later editing.
If you feel that Markdown is not your cup of tea you can disable Markdown formatting by using the `View > Use Markdown highlighting` menu
# Syntax, as used by Metanota
Metanota tries to stick as close as possible to the original Markdown specs. However, some adaptations have had to be made to accommodate the _highlighting_ approach explained above. And of course, bugs and/or wrong implementation decisions should be expected, as always.
Let’s take a look to the most common syntax elements :
Each paragraph is terminated with a new line, like in any other usual text editor. Metanota will insert a little space between paragraphs, just enough to make them visually distinctive.
On the same idea, any blank line will between paragraphs will have a smaller height. This is useful if you want to leave more space between paragraphs but a full empty line is too much.
Probably one of the most useful feature in a note editor is the possibility to visually and syntactically split your content using nested headers.
Headers can be inserted by using a variable number of `#`s at the beginning of a line, like this:
# this is header 1
## this is header 2
### this is header 3
#### this is header 4
An alternate method to use the first two header levels is to use the following syntax :
Lists are another very useful feature to use in a note and simple to use too.
### Bulleted lists
All you have to do is to insert a dash `-`, plus `+` or star `*` at the beginning of a new line, add a space and then some text.
Please note that a blank line on top of your list is needed after a normal text paragraph.
Let see an example :
- First item
- Second item
- A longer line A longer line A longer line A longer line A longer line A longer line A longer line A longer line A longer line A longer line A longer line A longer line A longer line A longer line A longer line A longer line A longer line A longer line
- Last item
Nested list can be used by adding tabs or spaces at the beginning of the line :
- First line
- Second line
- Nested line
- Another nested line
- Third line
### Ordered lists
Numeric lists are supported too, but without auto numbering.
1. Item 1
2. Item 2
3. Item 3
Markdown uses mail style block quoting like this (the `>` angle bracket at the beginning of a new line):
>This is block quoted text.
>And another one.
>And the last one, little bit longer. And the last one, little bit longer. And the last one, little bit longer. And the last one, little bit longer. And the last one, little bit longer. And the last one, little bit longer. And the last one, little bit longer. And the last one, little bit longer. And the last one, little bit longer. And the last one, little bit longer. And the last one, little bit longer.
## Code blocks
If you need some lines of text to be interpreted literally you should use a code block. One can be created easily by starting the line with at least 4 spaces or 1 tab :
This is a code block.
And this one too
The code block should be separated from a normal paragraph or a list by at least one blank line.
Usual text attributes like bold and italic can be represented in Markdown like this : __bold__ and _italic_.
Alternatively the following notation can be used : **another bold** and *another italic*.
Please note that currently ***bold + italic text*** will not show correctly in Metanota. As you can see it shows as bold.
Another way of highlighting portions of text consists in using any number of matching backtick as shown here :
>This `text` is showing how to use backtick in `Markdown`. You can use ``several backtick`` like this or even ```more```.
Regardless of the number of matching backtick used, Metanota will highlight them using the same shade. This will most likely change in future releases, so please use them accordingly.
Links in Metanota can point to any external URL (no internal links between notes, yet) and will be opened in the default browser.
To quickly see where a link is pointing is enough to hover the mouse over the link and wait a little until a tooltip appears. Let see some examples :
### Automatic links
The simplest way of creating a link is by using angle brackets : <http://www.metanota.com>. Also note that the `http://` prefix is required.
Email links are detected too : <email@example.com>
### Inline links
This is [an example](metanota.com) inline link.
`http://` is optional in this case.
### Reference links
Markdown reference links can be used. They are harder to write but the resulting note is easier to read :
„ In the [Metanota application] you can use your already existing accounts created in [Simplenote] or [Evernote]. You can write me at the [support email address]. “
One additional benefit is the possibility to reuse cleanly the same reference anywhere in your note. If you need to link, for example, Evernote’s web site again you can do it [easily].