Markdown 101

What is Markdown?

Markdown is a very popular lightweight markup language that is easy to read both by humans and computers. It is safe to say that various Markdown flavors are used by millions of people on thousands of platforms, for all purposes ranging from simple “Read me” files and product documentation to complex scientific papers.

Markdown documents can be read as such using a text editor or viewer or converted to many other formats; usually to HTML, the lingua franca of the World Wide Web, but also to PDF, EUB and other formats.

Please note that there is no “canonical” version of Markdown. The original implementation created in 2004 by John Gruber with Aaron Swartz supports most tags a typical writer would need, but many variations and extensions have been added over the years.

In this document, we will stick to the basic Markdown elements and a few extensions that are especially useful for technical writing.

How do you open and edit Markdown documents?

Markdown documents are plain text files. As such, they can be opened in any text editor.

Most computers or mobile device will come with at least one text (or notes) editor.

Operating system or platform	Editor
Apple iOS	Notes
Apple macOS	TextEdit
Linux	vi / vim
Microsoft Windows	Notepad
Android	-

Default text editors for various operating systems

If you find that this default editor does not meet your requirements, you can choose from literally thousands of text editors and note-taking apps for the major mobile and desktop operating systems.

There are also web-based / online text editors, including some that will not even require a user account or any form of setup, such as Riseup Pad.

List of text editors at Wikipedia
Text editors on alternative.to – you can filter this list by various criteria.

There are also dedicated Markdown editors. For an (incomplete) list of Markdown editors and converters, see the Tools page on the Markdown Guide site or browse your operating system’s online app store.

You could even use a rich text editor or a classical word processor such as Microsoft Word for editing a plain text document – but in this case, you will need to save or export the Markdown document as a plain text document. If you feel more comfortable working with your favorite word processor, nothing speaks against this workflow. Just make sure to save your documents as plain text with UTF-8 character encoding.

How do you format content in Markdown?

Markdown is not a “What You See Is What You Get” format.

In a typical Word processor, you will find menu commands or buttons that allow you to set a word e.g. in bold or italics, and the word will be displayed in bold or italic type right away.

In Markdown and other lightweight markup languages, you enter simple control codes that will be converted to the proper format during conversion.

Here is an example of a text document formatted in Markdown:

### Writing Markdown is easy

In the English [Wikipedia](https://en.wikipedia.org/wiki/), 
you will find a _lot_ of interesting information. 
__Knowledge is important!__

1. A list item
1. Another list item

This short document can be converted to the following HTML presentation using a Markdown editor/converter:

Writing Markdown is easy

In the English Wikipedia, you will find a lot of interesting information. Knowledge is important!

A list item
Another list item

Markdown Reference

Find our own Markdown guide here. Other resources:

↻ 2024-06-27