Markdown Markup Language

Creating website pages without professional knowledge of HTML code can be done easily if you are familiar with Markdown. It lets you convert text from sources like Google Docs and MS Word into HTML code with just a few clicks.

If you haven’t already, it’s time to try Markdown, which makes writing, formatting, and converting text into HTML much faster and more efficient. To avoid compatibility issues with various output formats, read this article where we explore the basic and advanced Markdown syntax and share practical tips on how to use it most effectively.

What is Markdown?

Markdown is a text formatting syntax designed for web pages. It allows you to easily apply formatting like bold, italics, ordered lists, bullet points, headings, and more without knowledge of HTML text markup language.

In the past, HTML was the standard for web page formatting, along with XML and SGML. HTML uses tags to format text, which can be quite complicated for non-tech-savvy people.

When a web browser processes a web page written in HTML, it interprets the tags and applies the corresponding formatting.

Markdown was invented in 2004 by John Gruber and Aaron Schwartz to be highly readable and easy to write. It also automatically converts its simplified tags into HTML.

Though the Markdown markup language doesn’t include all the possible HTML tags, it covers the most common formatting options, making it a convenient choice for fast web content creation.

Why use Markdown?

Here are a few key features that set Markdown apart from other markup languages:

• Simplicity: Its syntax is straightforward and intuitive. It uses simple symbol combinations to denote formatting elements such as headings, lists, bold/italic text, links, and images. This simplicity makes it accessible to both technical and non-technical users.

• Platform independence: Markdown are plain text files, meaning they can be created and edited using any text editor. They can also be easily converted to other formats like HTML, PDF, or Word documents. This feature makes the language an ideal choice for content creation that needs to be shared across different devices and platforms.

• Readability: Markdown files are human-readable and don’t include complex tags like HTML. This makes it easy to write and understand the content without being distracted by the formatting code.

• Version control: It is widely used in version control systems like Git. When you track changes to Markdown files, it’s easier to see what content was modified, added, or removed compared to other formats like Word documents.

• Documentation and note-taking: Many developers, writers, and researchers use the Markdown editor for writing documentation, taking notes, or creating README files for projects.

• Popularity: This language is commonly used for writing content on websites, blogs, and forums. Many blogging platforms and content management systems (CMSs) support Markdown, making it easy to publish content online.

• Consistency: Since Markdown syntax relies on a fixed set of formatting rules, it helps maintain consistency across documents and ensures a uniform appearance for content.

• Ease of collaboration: When working with others, the Markdown language can streamline collaboration as it’s easy to merge changes made by different contributors.

Markdown syntax

With its minimal syntax, Markdown isn’t intended to be an HTML substitute. Its main goal is to foster readability, ease of writing, and editing. While HTML is a format for publishing, Markdown is a writing format.

At the core of Markdown syntax are a few basic structures that handle the most common elements of a webpage.

Headers are created with hashtags (#), with the number of hashtags denoting the level of the header. For example:

### Header 3

#### Header 4

Emphasis can be added to text using asterisks or underscores (_). For example, single asterisks or underscores will italicize text, while double asterisks or underscores will make it bold.

Creating lists in Markdown is also straightforward, with asterisks, plus signs (+), or hyphens (-) used for bullet points, and numbers followed by periods for ordered lists.

Links and images are embedded using brackets [] for the display text or alt text, and parentheses () for the URL.

Watch this video tutorial on how to use Markdown for more tips.

Challenging Markdown tasks

In case you need to include more complicated elements like tables, formulas, and diagrams, you will have to learn more advanced Markdown syntax. But once you’ve gone through these tasks, it won’t be a problem.

Markdown tables

To make tables in Markdown, use pipes | to delineate columns. Here’s a simple example of a Markdown table:

 | Header1 | Header2 | Header3 |
 | ------- | ------- | ------- |
 | cell1   | cell2   | cell3   |
 | cell4   | cell5   | cell6   |

This will create a table that looks like this:

Note that the number of dashes doesn’t need to match the width of the column, but there must be at least one. The pipes don’t have to line up perfectly, but it often helps to do so as it makes the raw Markdown more readable.

If you want to align the text in the columns, you can use colons :

- Left-align: :-------

- Right-align: -------:

- Center-align: :-------:

Here’s an example using different alignments:

| Left    | Center  | Right |
| :------ | :-----: | ----: |
| cell1   | cell2   | cell3 |
| cell4   | cell5   | cell6 |

You can also use Markdown table generators, for example this one, which allows you to see the visualization of the table as you type.

Markdown formulas

In Markdown, you can use LaTeX syntax to create mathematical formulas. This feature is not part of the core specification, so whether it works depends on the parser being used. Many systems that render Markdown, like Jupyter Notebooks and some wiki systems, support LaTeX math.

Here’s how you can typically write math in Markdown:

Inline math: Enclose the LaTeX code with a single dollar sign $ on each side. For example, writing

$y = mx + b$

will render as:

$y = mx + b$

Display math: For equations on their own line, you can enclose the LaTeX code with double dollar signs $$ on each side.

$$ E = mc^2 $$

It will render as:

$$E = mc^2$$

You can also use Latex editor that facilitates the creation of complex formulas containing fractions, square roots, etc. Here’s an example of how it works:

Note that if you’re using a Markdown editor that doesn’t support LaTeX, you might need to use an image of the equation instead or rely on HTML embedding if that’s supported.

Markdown diagrams

Creating diagrams directly within Markdown can be a bit more challenging since the language itself doesn’t have built-in support for diagrams. However, there are several ways to include diagrams in your Markdown documents, depending on the platform and tools you’re using:

Images: The most common approach is to create a diagram using diagramming tools like Lucidchart, draw.io, or even PowerPoint, then export the diagram as an image (such as a PNG or JPEG file), and then embed the image in your Markdown file. Replace Alt text with a description of the image and url with the URL or path to the image.

Watch this video tutorial to learn how to create diagrams with Lucidchart.

HTML embedding: If your Markdown renderer supports inline HTML, you could use HTML tags and possibly JavaScript libraries to create or embed diagrams.

Extensions and plugins: Some Markdown processors have extensions or plugins that can render diagrams written in special syntax. For example, if you’re working with GitHub’s version of Markdown, you may be able to use Mermaid, a JavaScript library that allows you to create diagrams using text definitions.

Note that not all Markdown processors support Mermaid, so you’ll have to check whether your platform does.

Use external tools and embed links: You can also create your diagrams in an external tool that provides shareable links (like Lucidchart) and simply link to the diagrams in your Markdown file.

Code integration in Markdown

In standard Markdown, you can form code blocks by indenting lines with four spaces or a single tab. If this method seems complicated, you might prefer using fenced code blocks. These can be created with three backticks (```) or three tildes (~~~), placed on the lines preceding and following the code block. The specific characters to use might vary based on the Markdown processor or editor you’re employing.

For more details on useful Markdown syntax, check out this guide.

You can also use a Google Chrome plugin to convert a Google document file into Markdown. Another option is an online converter for Word documents.

Note that the converted .md file may contain some errors or unnecessary symbols, which could result in the bugs we discussed earlier. However, equipped with tips from our article, you can easily handle them.

A good solution to make your life easier when working with Markdown is using developed tools, with which, you can work with .md files without having to deal with special syntax.

Markdown-compatible tools

Markdown can work in any browser. There are numerous tools that facilitate working with this editor by presenting a simultaneous view of Markdown and rich text.

Markdown editors are user-friendly platforms that transform text into HTML, simplifying the process for web content creators.

Let’s explore some of the widely used tools.

Typora

Typora is one of the most popular Markdown editors. It accommodates advanced functionalities including, but not limited to, mathematical symbols and diagrams. It also supports an extensive variety of export alternatives. With over 50 themes available, and guidance provided on creating custom themes, it’s evident why Typora is the go-to choice for a vast number of content creators.

Ghostwriter

Ghostwriter, a KDE-based open-source Markdown editor, provides a distraction-free writing experience through its full-screen mode. It features a minimalist, easy-to-navigate interface with theme customization.

One helpful feature is its live preview that promptly reflects your Markdown inputs. Additionally, it allows you to directly copy the HTML generated into a blog post for immediate publication without requiring modifications.

This becomes particularly useful for technical writers as it enables them to instantly upload files into version control systems for cooperative work, or publish them using static site generators like Readthedocs, among others.

Dillinger

Dillinger, a cloud-based, open-source, HTML5 Markdown editor, offers a smooth online editing experience that runs directly within your browser. It lets you preview and export your text in various formats, such as HTML, Styled HTML, Markdown, and PDF.

Offering a live split-screen preview, a selection of themes, and the flexibility to choose your preferred Markdown syntax for writing, Dillinger could be the comprehensive solution you need.

VSCode

While Visual Studio Code isn’t exclusively a Markdown editor, but it comes with Markdown editing abilities. For some advanced features such as shortcuts, generating a table of contents, and more, you can install an extension.

Visual Studio Code has dynamic side-by-side HTML previews, lockable previews, enhanced preview security, and the ability to customize your writing experience through several extensions.

Quiver

This platform allows users to seamlessly organize their Markdown notes and documents. Quiver provides a variety of themes to choose from and offers syntax highlighting. Additionally, it has a full-screen presentation mode that lets you showcase your notes, making it ideal for classrooms or team meetings where swift sharing is necessary. With its built-in full-text search feature, Quiver ensures that even within thousands of notes, you can quickly locate exactly what you need.

Ulysses

Ulysses is a versatile Markdown writing application designed for Mac, iPad, and iPhone. It’s a great choice for file organization and management, with the capacity to store all your notes and drafts. Plus, it allows effortless export and sharing with your team or audience. With its layout featuring a sidebar, sheet pane, and content pane, Ulysses ensures your resources remain well-organized and readily available whenever you need them.

Designed with high mobility in mind, Ulysses allows you to jot down your thoughts whenever inspiration hits, without the need to worry about synchronizing your content across different devices.

iA Writer

iA Writer is a user-friendly Markdown editor. Its key features include syntax highlighting, style check, drag-and-drop images, a variety of templates, and export capabilities in HTML, Word, and PDF formats. It also offers easy navigation between documents and a history feature to revert to past versions. iA Writer’s focus mode allows efficient line-by-line editing, making it a popular choice among users. It’s compatible with Windows, Mac, Android, iPhone, and iPad, and is available through a one-time payment for all platforms except Android.

Markdown vs. WYSIWYG editor

WYSIWYG stands for “What You See Is What You Get.” It is an editor that allows users to directly manipulate content on a digital platform, such as a document, webpage, or graphic, while offering an accurate view of how it will appear to end users. In other words, as you edit and format the content, you can instantly see the final output as it will appear to viewers; there’s no need to visualize or interpret complex codes or markup languages. WYSIWYG editors are widely used in various applications, providing an intuitive and user-friendly experience, especially for individuals who may not have technical expertise in coding or formatting.

To learn more about the differences between Markdown vs. WYSIWYG editors, watch this video:

Why should you consider using Markdown over a WYSIWYG?

Using Markdown over a WYSIWYG editor offers several advantages.

Portability

Markdown files are plain text files with minimal formatting. They can be opened and adjusted with a simple text editor on any device. In contrast, WYSIWYG editors may use proprietary file formats or require specific software to access and edit the content.

Consistency

Markdown offers a consistent look across various platforms and devices since it ultimately converts to HTML. WYSIWYG editors may produce inconsistent results depending on the software used to view the content.

Lesser risk of code errors

WYSIWYG editors can sometimes introduce hidden code errors, especially when copying and pasting content. Markdown, being plain text, minimizes such risks.

Wider compatibility

Markdown is supported by a broad range of platforms and applications. Its universality ensures the content can be easily migrated or shared across different systems without losing formatting.

When making a choice between Markdown and WYSIWYG, consider the following.

If you’re dealing with a massive amount of content spread across various platforms like the web, internal knowledge base, and print materials, and you want a hassle-free solution, WYSIWYG is the best fit.

However, if you’re looking for a simple and efficient way to create well-formatted text documentation without any fuss, then Markdown could be the perfect choice for you. It’s easy to use and helps you get the job done quickly.

Tips to overcome Markdown bugs

When you are using Markdown, you may sometimes notice that the published text does not display correctly on the web page. This happens when you make a mistake in using the opening or closing Markdown syntax. Sometimes the reason can be the extension or application you employ to convert other formats to Markdown, which provides a file with some missing or unnecessary syntax.

Here are some examples of errors that can occur when using Markdown.

Conflicting emphasis

Emphasizing text with both single and double asterisks or underscores may lead to conflicting formatting. Stick to a consistent style.

This is **incorrect* emphasis.

This is **correct** emphasis.

Incorrect link format

Links must include the full URL, including the protocol (e.g., http:// or https://).

Incorrect:

[Incorrect Link](www.example.com)

Correct:

[Correct Link](https://www.example.com)

Table formatting

To create a well-formed table, make sure each row has the same number of cells as the header row.

Incorrect

|  Name | Age | Gender |
|:-----:|:---:|
| John  | 25  |
| Alice | 23  |

Correct

|  Name | Age |
|:-----:|:---:|
| John  | 25  |
| Alice | 23  |

It will render as:

Code blocks

To define a function in a code block, remember to include parentheses after the function name:

Incorrect

```python def say_hello: print("Hello, World!")

Correct

```python def say_hello(): print("Hello, World!")

Incorrect image tag

The correct image tag should include the file extension (e.g., .jpg, .png, etc.).

Incorrect

![Image Name](path/to/image)

Correct

![Image Name](path/to/image.jpg)

If you have issues with Markdown implementation, get in touch with the Serokell team.

Comparison of markup languages

Different markup languages have specific purposes and syntaxes tailored to their intended applications.

In the following table, we provide a comparative overview of popular markup languages, highlighting their purposes, syntax, file extensions, extensibility, browser support, and complexity.

Conclusion

Markdown provides a simple yet powerful syntax for formatting text. Its straightforwardness and ease of use make it an essential tool for anyone involved in writing for the web. Whether you’re a developer documenting code, a writer crafting a blog post, or a researcher drafting an academic paper, Markdown can streamline your workflow and make the writing process more efficient.

While it might take a little time to learn the more advanced elements like tables, mathematical formulas, and embedding diagrams, the effort is certainly worth the investment. As more platforms adopt and extend Markdown support, its importance in the digital writing landscape will only continue to grow. Understanding and mastering Markdown is a valuable skill, helping you create well-structured, readable, and portable documents with ease.