Introduction to Markdown

Markdown is an efficient way to generate and store content for the web. In this introductory guide you will learn what it is, how it works and how it can benefit your company or organization.

• What is Markdown?
• What is a markup language?
  • This is a heading
• Why use Markdown in your company?
• Flavors and Specification
• CommonMark
• Who uses Markdown?
• How does Markdown work?
• Commonly Used Markdown Syntax
• How is markdown stylized?
• How to use it in the day-to-day of my company?
• Notes
• References

What is Markdown?

Markdown is a light markup language used to format plain text, created by John Gruber in 2004 as an easy-to-read language. It is widely used today by bloggers, journalists, researchers, programmers, and the general public to create content on websites, documents, pdfs, notes, books, presentations, emails, and technical documentation. It is also used in instant messaging, online forums and collaborative software.

Markdown is a great way to create web content and content in general in your organization

What is a markup language?

A markup language is a text coding system that defines the structure and format of a document. A markup language can control the display of the document as well as add metacontent. HTML, XML, LaTeX, are examples.

In HTML the content is surrounded by tags, such as a <p> to denote a paragraph, a <strong> to denote importance published as bold, or <h3> for a third-level heading. To add bold text in markdown, simply add ** to the beginning and end of the word, and to add a heading, use #, where the amount of # denotes depth.

HTML example:

HTML

<h3> Example </h3>
<p> I'm a paragrah in <strong> HTML </strong> </p>

A light markup language aims to be simple to read and write.

Same example in Markdown:

MARKDOWN

### Example
I'm a paragrah in **HTML** 

Markdown can be written in any text editor (whether on Windows, Mac, Linux) and has the extension .md or .markdown In the web context, a markdown file is transformed into HTML which is then displayed in the browser.

For example, the following markdown:

MARKDOWN

### This is a heading

- A **list item in bold**
- A [link](/en/blog/introduction-markdown)
- A ~~crossed off list item~~
- A footnote [note 1](footnote:1)

It is displayed on the web as:

This is a heading

• A list item in bold
• A link
• A crossed off list item
• A footnote ¹

Why use Markdown in your company?

Most of your employees, clients, and suppliers are used to “WYSIWYG” editors. WYSIWYG is an acronym in English, “What you see, is what you get”, which means what you see in the editor is what you see published in the final format. For example, when you create bold text in Microsoft Word and publish it as a PDF, in both Microsot Word and the PDF, the text is seen in bold. However, bold text in Markdown is seen in the text editor as **bold text** instead of bold text as it looks in the browser.

Why write with Markdown when you can press buttons in an interface to format text? It turns out that there are several reasons why Markdown makes sense and is used in the business world instead of WYSIWYG editors.

• Allows version control over content. Especially useful for content-heavy organizations where content teams can create automated workflows using version control tools such as git/mercurial/fossil/darcs ².

• It’s simple. It’s easier and friendlier than editing direct html, and it has a super-fast learning curve.

• Markdown is a content persistence layer. The content is stored in markdown format that is readable by humans and serves on its own as a way to store content. It can be saved in a database, created backups and manage versions of documents.

• Multipurpose language. Markdown can be used to create websites, documents, notes, books, presentations, emails, and technical documentation. In particular, your company’s knowledge base can be created and stored in markdown format.

• Portability. Markdown files can be opened and edited with virtually any text editor (Notepad, TextEdit, Vim, Word, etc). In turn, you can import Markdown files into any other Markdown application. That’s in contrast to apps like Microsoft Word that lock their content in a proprietary file format (example.docx).

• Multiplatform. Windows, Mac, Linux, Android, etc. You can create Markdown files on any device with any operating system.

• Temporal robustness. Only a text editing application is enough to read a markdown file, unlike formats that require specific applications that may stop working or disappear from the market. This is an important consideration when it comes to books, university theses, and other important documents that need to be preserved indefinitely.

• Greater efficiency. It is enough to use a simple text editor without the need to load heavy software or open a browser, consuming less memory and CPU.

• Effective for creating content. It streamlines the content creation process compared to alternatives such as writing content in CMS via WYSIWYG. On the one hand, it avoids corrupting content (which usually happens in editors like WordPress) and on the other hand, it allows you to focus only on the content. People who create a lot of content like journalists, researchers, and bloggers prefer it.

• Markdown is very useful in AI. Many artificial intelligences understand Markdown. For example, if you tell ChatGPT “the important part of this example sentence is the word that is in bold”, ChatGPT will not understand it. If, on the other hand, you say the same thing in markdown language, that is: “the important part of this **example** sentence is the word that is in bold” ChatGPT will understand that this word is a “example”. In turn, markdown is widely used to feed and train AI models.

You can consider markdown as a de facto language for your organization’s content. Easy to read and edit by humans, with excellent support of tools to be managed by teams and with enough expressive power to be transformed into publication formats (website, pdf, etc).

Flavors and Specification

There are different variants (”flavors”) of the language where new functionalities are added by defining new syntax. For example, Markdown Extra is a variant implemented in PHP, Python and Ruby programming languages that allows you to add html attributes such as id or class to elements such as a paragraph or a link, using the {#id.class} syntax. In turn, different organizations adapt the language according to their business needs.

Extra Markdown Example:

MARKDOWN EXTRA

### Heading {#my-id .my-class}

Besides different flavors, the original canonical description of Markdown’s syntax does not specify the syntax unambiguously. Perhaps the most interesting work about it is Commonmark, which is an specification of Markdown, aiming to provide a standarized spec, officially adopted by several companies such as Discourse, GitHub, GitLab, Reddit, Qt, Stack Exchange (Stack Overflow), and Swift.

Injeniero uses Commonmark because we considered potentially more sustainable as an standard and because of its philosophy of rigor in its specification which produces fewer errors

It should be noted that Markdown accepts writing html directly.

That is, the following markdown is valid:

MARKDOWN

### Example 2
This markdown is valid 
 <div id="myDiv" class="myClass"><span> Adding inline HTML in a markdown file </span></div>
Other paragraph

This provides great flexibility by being able to add HTML elements directly. However, on the one hand, it is mixing formats with different functions and on the other hand it adds potential for security vulnerabilities. For example, adding a malicious script inside the markdown file that is executed when rendered as html by a browser.

An alternative (which we recommend) is to use strict libraries that do not allow you to write direct HTML, but they do support some extensibility in functionality. At first strict libraries seem limiting, but they ensure superior quality control and safety. Fewer errors, and explicit errors that make them easier to correct. Libraries such as MMark in Haskell 1, use this philosophy, allowing HTML to be created from markdown with greater security and error control, as well as allowing extensibility to add utility according to business requirements.

For example, at Injeniero we created an extension in MMark to produce sustainable images in Markdown (read Sustainable images in Markdown using MMark Haskell)

Injeniero uses MMark, a strict library in the Haskell language, with a CommonmMark specification that increases security and facilitates error-free HTML files

CommonMark

As we mentioned, one of the problems with Markdown is that it doesn’t specify the syntax unambiguously. Because there is no unambiguous specification, a number of different specifications emerged in the last 10 years. As a result, syntax of a variant is displayed differently in different Markdown systems. Also, due to the lack of a “syntax error,” errors are difficult to find and fix 2.

For these reasons, in 2019 a group led by Jeff Atwood and John MacFarlane, released a first version of CommonMark with the long-term goal of being a Markdown standard and providing a series of tests to validate implementations that use this specification.

Every page on our Injeniero website is created using CommonMark, including this

Who uses Markdown?

It is currently widely used especially by content creators such as bloggers, journalists, writers and researchers. It is also widely used for the preparation of technical documentation and global companies such as Github and Reddit use it daily.

There is a great opportunity in B2B organizations to take advantage of Markdown’s business advantages

How does Markdown work?

Basically, a markdown file, which has an .md or .markdown extension, is processed by an application, which transforms it into html. There are many applications available, from simple scripts to desktop applications that resemble Microsoft Word. Despite their visual differences, all apps do the same thing. They all convert Markdown-formatted text to HTML so that it can be displayed in web browsers. In particular, many programming languages such as Python, PHP, Ruby, Go, Node, Haskell, etc, have libraries that transform markdown into html.

At Injeniero we created our own static website generator ³ that processes markdown using the Haskell MMark library, which allows us to create amazing sustainable websites, ecommerce, and blogs, with exceptional maintainable content and loading speeds.

Commonly Used Markdown Syntax

Headings
-----------

# H1
## H2
### H3

Bold
-------

**bold text**

Italic
-------

*italic text*

Blockquote	
----------

> blockquote

Ordered list
--------------

1. First item
2. Second item
3. Third item

Unordered list
---------------

- An item
- Other item
- Last item

Code
------

`code`

Link
-----

[alt link](https://www.injeniero.com/en)

Image
------

![alt description](image.avif)

Table
------

| Syntaxis    | Description |
| ----------- | ----------- |
| Heading     | Title       |
| Paragraph   | Text        |

Crossed off
-------
	
~~crossed of text~~

How is markdown stylized?

In web context, Markdown is transformed into HTML via an application and therefore it is possible to add styles as to any HTML using a style sheet (css). In case of strict libraries that do not allow adding direct html or adding classes to elements directly, you can use css selectors instead of classes.

For example, to make the first letter of the first paragraph of an article red in large text:

CSS

body p:nth-of-type(1)::first-letter {color:red; font-size: 3rem;}

With good use of css selectors, it is possible to style websites made in markdown with strict generators. In fact, the website you are reading is generated entirely with CommonMark and styled via css

How to use it in the day-to-day of my company?

Markdown is super easy to learn and the best way to learn is by writing. However, it is not necessary to learn it to enjoy its benefits if you hire us.

Injeniero includes in all its plans the updating of content by receiving plain text files by email. For those who want more independence we provide a service where they can upload markdown files and visualize the result with the design of their company’s website.

Notes

1. Markdown is cool ↩
2. Interesting article of why not use git why not git, and use fossil in companies that use content version control. ↩
3. There are many static website generators on the market such as Hugo and Jekyll, among others. However, at Injeniero we decided to create our own system, giving us full flexibility for the creation of websites. ↩

References

1. ^ MMark Haskell, Mark Karpov Announcing MMark
2. ^ CommonMark CommonMark.org