Markdown guide

by Yorik on 02.06.2021 in linux , opensource

What is it?

A simple way to write text and add some structure to it, without using any special program
There are hundreds of free and open-source applications to play with, that make the whole writing experience better or "render" your markdown files beautifully by applying styles to it
Your markdown texts are easy to convert to almost anything: web pages, doc or pdf documents, etc... and are natively handled by many platforms and systems

Markdown is a kind of genial hack: It is not a program, nor a programming language, it is a way to write text, anywhere, with any tool or program, to make your text both easy and elegant to read by humans, even without any fancy program, and also easily understandable by a computer, so it can detect titles, sections, lists, and various kinds of formatting such as bold, italic, etc.

Since it is just a way to write text, you don't need any special tool or program to write markdown. You can use it anywhere you can write text, such as email, notepad, etc. There are specific programs too, which can do more tricks such as rendering titles differently while you type, and much more.

Since it is also easily understandable by a computer, it is very easy to convert markdown text to other formats such as HTML, DOCX, ODT and basically any other text format. Since it is very simple, conversion problems are basically a thing of the past.

More and more platforms, websites, and programs understand and render markdown text, so it is basically becoming the most universal, open, fail-safe, easy to use text language ever.

Markdown files are basically just normal text files, so you can simply save them as .txt files, but you can also use the .md extension so you and your programs can more easily recognise them.

Example

# This is a title

## This is a second-level title

### This is third-level title. You can go this way as far as you need

This is just normal text paragraph, you can write it in one go, letting your program or editor do the line breaks automatically, like you would do in Word, or if you prefer (some people prefer), you can just do the line breaks yourself:

This is a paragraph where I did the line breaks
myself, that is, I pressed Enter myself where
I wanted to make the text block smaller. This
is sometimes preferred, for example when writing
pure text emails, in code editors, etc. This
will still be considered as one paragraph.

This is a list of items:

- First item
- Second item
- You can even do a list with
  multiple lines
- Fourth item

This is *italic text*

This is **bold text**

This is a [clickable link](https://wikipedia.org)

This piece of text is both easy to read as is, without any program or formatting, and looks like this when rendered as HTML. The text below uses the style of my blog, but basically it depends on where you open it. The idea is basically that in your text you concentrate on defining what is text, what is title, etc... and not care about how it looks. That will depend on where you open the file:

This is a title

This is a second-level title

This is third-level title. You can go this way as far as you need

This is just normal text paragraph, you can write it in one go, letting your program or editor do the line breaks automatically, like you would do in Word, or if you prefer (some people prefer), you can just do the line breaks yourself:

This is a paragraph where I did the line breaks myself, that is, I pressed Enter myself where I wanted to make the text block smaller. This is sometimes preferred, for example when writing pure text emails, in code editors, etc. This will still be considered as one paragraph.

This is a list of items:

First item
Second item
You can even do a list with multiple lines
Fourth item

This is italic text

This is bold text

This is a clickable link

The rules, condensed

The rules are very simple, searching the net for "markdown" will immediately bring you many guides, cheat lists and all you need, but they are really easy to remember:

Headers, sections, titles: # for header 1, ## for header 2, etc. There are also alternative ways for headers 1 and 2 if you prefer: Just underline the header with === (header 1) or --- (header 2). There is no need to have the same number of = or - as the text above, just use at least 3:

Header 1    or     # Header 1
========

Header 2    or     ## Header 2
--------

Bold, italic, strike through: Just close a piece of text inside * (italic) or * (bold) or ~ (strike through). Make sure the / ** / ~ touches the text:

*Italic text*
**Bold text**
~Strike-through text~

Links and images: the text of the link goes into [ ], immediately followed by the URL the link points to, in ( ). To display an image, just add a ! before the link. The alt text is not necessary (you can leave it simply empty like this: ![] but it is a good practice to add a description of your image, both for yourself if you read the text without seeing the images or for blind prople:

This is a [link to Wikipedia](https://wikipedia.org)

This is an image taken from the internet (without alt text):
![](https://freecad.org/images/freecad-logo.png)

This is an image taken from the same folder where your markdown file lies:
![alt text](my-image.jpg)

This is an image taken from an "images" subfolder:
![alt text](images/my-image.jpg)

Lists: You can make bullet list using - or *, or numbered lists using 1., 2. or 1), 2)...:

This is a bullet list:
* item 1
* item 2

This works too:
- item 1
- item 2

This is a numbered list:
1. item 1
2. item 2

This works too:
1) item 1
2) item 2

This is a checkbox-style list, useful for task lists:
* [ ] item to do
* [ ] other item to do
* [x] this item is done

There is more, but my aim here is to keep it simple. Check this cheatsheet for something more complete.

Applications / how to

There is nothing more to know, really. You can just start writing markdown anywhere such as in your email program, in a note taking application, etc.. As you can see above, to make best use of aligning, it is always better to use a mono-space font (basically any font with "mono" in the title, where every character has exactly the same width), but it's a matter of choice.

There are also specific applications, which can for example apply formatting to your text as you write, so # headers will immediately render with a bigger size, etc. For example:

For desktop (Mac, Windows and Linux):

Mark Text: For Mac, Window and Linux, free and open-source, packed with under-the-hood features, themable, in my opinion the best of this stack. Only exports to HTML or PDF
Abricotine: For Mac, Windows and Linux, free and open-source, a bit more classical and less beautiful as Mark Text, but still an excellent markdown editor. Can export to all formats supported by Pandoc
Ghostwriter: For Mac, Windows and Linux, free and open-source. Very similar to Abricotine.
Typora: For Mac, Windows and Linux, free to use but not open-source. Probably the easiest to start with and get hooked to markdown. Super elegant and cool to work with, and packed with features. Can export to many usual file formats
Panwriter: An interface for Pandoc, it also works online

Online platforms (use in a browser):

Panda editor: This one is online so it works inside the browser on any platform, free and open-source. It uses another paradigm, which is to render both your normal text and the rendered text side-by-side. Some prefer it. In any case it is great to have a quick try at writing markdown!
Jotterpad: An online platform (you can use it inside a browser) with also apps for Android and IOS. Feee but not open-source, it requires an account on the platform to unlock some features.

Mobile (Android / IOS):

Markor: Android only. Free and open-source, it does the job well and can be used with sync platforms like Dropbox or Nextcloud. But it only exports to HTML.
Writer Plus: Android only, Free but not open-source, a very clean and simple writing app that works with markdown.

Conversion

Pandoc: Markdown converts or opens easily to almost any other language or format. Pandoc is is a great, open-source utility that converts between formats, and you can also use it online at https://pandoc.org/try/ and there is an installable interface utility for it called panconvert
Cloudconvert: Another online platform to convert markdown text to many formats