Many AI and software engineering tools build on the Markdown notation for structuring and formatting textual information and input. With the continuing spread of AI assistants the importance of Markdown increases.
This article aims to provide a quick introduction to Markdown notation and its productive use. To that end, it compiles what I find the most useful information resources on the topic in the style of a question-and-answer article. It addresses the following questions:
- What is Markdown?
- What are the advantages of Markdown?
- How can I learn Markdown?
- What tools help with Markdown?
- Where can I find useful information about Markdown?
What is Markdown?
Markdown is a notation for structuring and formatting textual information and input. It works on plain text files in order to make them easy to write and read, with a small collection of essential and intuitive markings, such as two stars („**“) for setting text in boldface or hyphens („-“) for marking bulleted lists.
Let’s look at an example. The following text highlights some of the most important elements of Markdown.
# Heading Level 1
This paragraph contains words in _italics_ and **boldface**, as well as a link to [an important Markdown-related website](https://commonmark.org/).
## Heading Level 2
A nested bulleted list contains:
– Item 1
– Item 1.1
– Item 1.2
– Item 2
– Item 3
There are also enumerated lists. Separator lines exist, too:
—
There are up to six headline levels. Another way to mark level 1 and 2 headers is with double and single underlining:
Alternative Heading 1
=====================
Alternative Heading 2
———————
That is basically it.
When you can type text anywhere in a computer or mobile device, you can use Markdown to structure and format it. For this reason, the notation has rapidly become popular among software developers.
With the spread of generative AI systems, Markdown has experienced another boost. Because it is a very economic way to express the structure of textual statements. AI assistants are very good at processing Markdown input and often use it as the output format for their results.
You can easily convert a Markdown text file to HTML or an Office format. The ability to convert to HTML was one of the initial requirements for developing the notation. Therefore, Markdown users are not restricted to proprietary formats or specific vendors’ products. Markdown is a free, open format. Documents in Markdown are highly flexible and durable.
The Markdown notation was created in 2004 by John Gruber in collaboration with Aaron Swartz. Its popularity grew rapidly, causing many new implementations to appear. However, since the initial specification was informal and contained ambiguities, the use and compatibility of Markdown variants began to suffer.
In 2014, the CommonMark initiative began developing a clearer, more interoperable Markdown specification. CommonMark and its extension in GitHub Flavored Markdown (GFM) are now the de facto standards of the notation.
What are the advantages of Markdown?
The main advantages of Markdown are:
- Easy to read
- Quick and easy to write
- Ability to write in a distraction-free mode
- Easily convertible to other formats
- Very low processing overhead
Distraction-free writing means that you do not need to worry with the usual text formatting actions involving mouse positioning and menu selections. This allows you to focus entirely on thinking and writing while the essential formatting flows naturally.
Ease of conversion comes from the Markdown to HTML conversion built in and available from Day One. From HTML, many additional conversions are available easily, including Office documents and PDF.
Markdown’s low processing overhead is a major advantage for AI systems. Plain text lacks information. Other document formatting notations and file formats, such as HTML or PDF, are much more costly to analyze and create.
However, Markdown has some disadvantages that should not be ignored. In particular, these are:
- It has a technical touch, and it is sometimes difficult for non-computer people to access
- There are many dialects, which may limit the compatibility and exchange of documents
These disadvantages can be mitigated. Concerning Markdown’s technical aspects, users should equip themselves with a minimum of tooling for dealing with plain text or Markdown files. One option is a text editor like Notepad on Microsoft Windows platforms. There are also specialized Markdown editors available. They let you type and edit in Markdown notation at the cursor position. However, all other text appears in rich text formatting.
If you find yourself working with tools that use different Markdown dialects, it can help to focus on the core notation elements of CommonMark and GitHub Flavored Markdown. You may also develop the habit of using specific conversion paths, tools, and automations for your typical workflows.
How can I learn Markdown?
Start with the CommonMark Quick Reference Card for an overview of the core notation elements. Then take CommonMark’s interactive online tutorial, which will take only a couple of minutes.
Afterwards, you are ready to start using the Markdown notation in your own texts and documents. The easiest way is to use the online Markdown editor Dillinger.io.
Later, you may check out some tools from Matt Cone’s extensive tools directory and install them on your computer.
As you become more familiar with Markdown, you will probably want to explore more advanced notational elements. Good starting points for further orientation are the advanced notation of GitHub Flavored Markdown and the recommendations and best practices contained in Matt Cone’s Basic Syntax page.
What tools help with Markdown?
First, you can start writing Markdown in every editor that works on plain text. Your computer came with this kind of software, such as TextEdit on macOS or Notepad on Windows. And there are plenty of more advanced alternatives available on the market.
Second, specialized Markdown editors display text in the rich text format that we are accustomed to seeing on web pages and in office suite text processors. However, when you place your cursor in the text, the surrounding area switches to the underlying Markdown text, enabling you to write or edit directly in Markdown notation.
Some of these Markdown editors have user interfaces with two text frames. One frame is a plain text editor in which you write Markdown. The other displays the formatted text immediately while typing. One example is the online editor Dillinger.io. It is free and offers a very good basis for exploring Markdown.
Third, many tools use Markdown for text editing and as their internal representation format. These tools may be software development environments, discussion forums, personal note-taking and knowledge management applications, or text authoring tools for professional writers.
Matt Cone has compiled an extensive list of Markdown-related tools. Each tool comes with a detailed description.
Where can I find useful information about Markdown?
The following lists summarize the links that are mentioned in the other sections. They also include additional topics and references.
Introductions to Markdown
The recommended starting point for entering into Markdown is the CommonMark initiative. It offers a concise introduction and overview page: https://commonmark.org/
CommonMark’s overview table of the main notation elements (Markup in 60 seconds): https://commonmark.org/help/
CommonMark’s interactive tutorial (Markup in 10 minutes): https://commonmark.org/help/tutorial/
For GitHub Flavoured Markdown (GFM), which fully includes CommonMark, the following web page describes the basic notation under the title Basic writing and formatting syntax: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax
The web page Working with advanced formatting addresses the extensions that GFM makes to CommonMark: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting
Matt Cone’s website Markdown Guide contains, among other information, a Markdown notation cheat sheet and a very good introductory overview.
The Markdown Cheat Sheet: https://www.markdownguide.org/cheat-sheet/
The introduction text about Markdown, Getting started: https://www.markdownguide.org/getting-started/
Discussion forums on Markdown
The CommonMark initiative offers a discussion forum: https://talk.commonmark.org/
Other more general discussion forums where you can ask and find information on Markdown are:
- Reddit: https://www.reddit.com/r/Markdown/
- Stack Overflow: https://stackoverflow.com/search?q=Markdown
Markdown tooling
For a head start into Markdown, the online Markdown editor Dillinger.io is particularly useful: https://dillinger.io/
For an extensive list of Markdown-related tools check out Matt Cone’s tools directory: https://www.markdownguide.org/tools/
Advanced information on Markdown
If you want to dive deeper into the details of Markdown, you may consult the specification documents of CommonMark and GitHub Flavored Markdown:
CommonMark specification: https://spec.commonmark.org/
GitHub Flavored Markdown specification: https://github.github.com/gfm/
Matt Cone provides a page titled Basic Syntax. It introduces the various syntax elements along with recommendations and best practice on how to use them: https://www.markdownguide.org/basic-syntax/
Additional information
If you want to explore other and more detailed information on Markdown, then the following websites are worth a visit.
John Gruber’s original Markdown site at his Daring Fireball blog: https://daringfireball.net/projects/markdown/ presents the initial 2004 version of Markdown. it is very informative. However, be aware that nowadays the more authoritative notation definitions are those of CommonMark and GitHub Flavored Markdown.
The Markdown Guide website by Matt Cone, already referenced repeatedly above, contains several other kinds of useful information. You may start from its homepage: https://www.markdownguide.org/
The Wikipedia page Markdown provides an informative overview of the Markdown notation: https://en.wikipedia.org/wiki/Markdown
Image source: Andreas Birk