Blogging With Markdown: All You Need to Know

If you’ve chosen to start blogging with Markdown, this article offers an introduction to the Markdown syntax, an overview of the most popular Markdown editors, and technical guidance for creating blog posts with Markdown using manual conversions, WordPress plugins, and the top static site generators.

Benefits of Markdown

Markdown reduces the overhead involved in formatting posts. Writers don’t need to worry about HTML tags, allowing them to focus on content creation without distractions.

In addition, Markdown is version control friendly since its plain text format allows for easy tracking of changes with Git, SVN, etc.

Getting Started With the Markdown Syntax

Markdown allows you to use special characters to format your blog articles.

For example, you can create a level 1 heading by adding the # character at the beginning of a phrase.

# A Step-by-Step Guide to Building Your First Website

Create a subheading of a specific level by adding the # character multiple times:

## Choosing the Right Domain Name

Make a phrase bold by adding two asterisks before and after specific words:

When building your first website, **choosing the right domain name** is one of the most important steps. Your domain name represents your brand and is the first thing people will see.

Create a link by adding the link text in square brackets followed by the link URL in round brackets.

For further guidance, check out [this in-depth guide](https://www.example.com/choosing-domain-name) that outlines the best practices and common pitfalls to avoid.

For more information on the Markdown syntax, see the Basic Syntax article on the Markdown Guide site.

Editors

If you plan to write your articles outside your blogging platform, you need a Markdown editor. Some popular options include:

Typora

Typora is a popular Markdown editor that can be installed on any operative system.

This editor has a minimalistic, distraction-free UI. It allows you to type Markdown syntax directly in the editor or to select the Markdown element from the menu bar.

This editor includes features such as:

• Live preview
• Import and export
• Word counters
• Typewriter mode
• A sidebar to manage files
• Document outline
• Spell check
• Many options to configure the supported Markdown syntax

From the Download page, you can obtain the 15-day free trial or purchase the complete version for $14.99.

Visual Studio Code

It’s easy to use the open-source code editor developed by Microsoft as a Markdown editor. Simply proceed with these steps:

1. Create or open a Markdown file
2. Enable the Markdown preview by clicking the Open Preview to the Side button on the top-right section of the UI
3. View the structure of the Markdown file in the Outline section

For more advanced features, a plugin like Markdown All in One will give you keyboard shortcuts, support for additional Markdown flavors, and more.

Obsidian

Obsidian is a Markdown-based note-taking and knowledge management application that has gained popularity in the last few years. It’s used by a large variety of users, including content creators, students, writers, researchers, developers, and project managers.

Obsidian includes powerful features like bi-directional linking, graph view, backlinks, and tagging. However, it has the highest learning curve among the listed programs for creating Markdown documents, so I recommend taking lessons or a tutorial before starting with it. To learn the basics of Obsidian, you can refer to this Getting Started Guide or watch this introductory video.

Dillinger

Dillinger is an online Markdown editor used by writers, students, and developers.

This editor is very easy to use. After accessing the dillinger.io page, you will be presented with a split-screen interface with the Markdown document on the left side and the live preview on the right side.

To save the documents created with Dillinger in the storage provided by your favorite cloud service, use the Services section on the left sidebar. Here, you can connect Dropbox, Google Drive, One Drive, and other services with Dillinger.

An integration with GitHub is also provided. This feature allows you to send Markdown documents created with Dillinger to your GitHub repository.

Technical Solutions to Use Markdown in Your Blog

Manually Convert Markdown to HTML

Pandoc

Pandoc is a document converter that supports many formats, including Markdown, HTML, PDF, and others. Downloadable packages are available as Windows installers, deb files for Debian-based Linux distribution, pkg files for Mac OS, etc. The installation procedures are available on this page.

I tested Pandoc on the Fedora Linux distribution; in this context, the package is already available in the repository, and downloading the files from the Pandoc site is unnecessary.

Let’s begin. Use the command below to test if the Pandoc package is available. If the package exists, you will see the package name, version, release name, and other information on your terminal.

dnf info pandoc

If the package is available, install it with this command, and when requested, enter your password:

sudo dnf install pandoc

Now we can convert Markdown to HTML using the pandoc command with a few options:

pandoc -f markdown -t html5 -o output.html input.md -c style.css

Let’s explain this command:

• With the -f option, we defined the input format, which, in this case, is markdown.
• The -t option sets the output format, in this case html5.
• The -o option is used to specify the output file name.
• The -c option sets a CSS file to be included in the output of the HTML5 document.

After converting your Markdown document to HTML in Pandoc you can upload the resulting HTML document to your blog via FTP.

Convert Markdown documents in WordPress

Many site administrators are transitioning from WordPress to Markdown-first blogging platforms; however, this is only sometimes necessary because WordPress has great tools to work with Markdown.

Ultimate Markdown

With Ultimate Markdown you can convert your Markdown documents to WordPress posts using dedicated editor functionalities.

To begin, log in to WordPress, and install Ultimate Markdown from the Plugins menu. Then, create a new post and open the Import Markdown sidebar. Here, click the Upload file and import button and select the Markdown document you want to convert to a WordPress post.

The plugin will create the new document directly into the block editor. Front Matter fields are also supported to configure the metadata of the WordPress posts.

In addition, there is a dedicated bulk import menu to convert multiple Markdown documents to WordPress posts.

For more information on the plugin features, please see the Ultimate Markdown page on our site.

Jetpack

With Jetpack, the popular plugin for WordPress developed by Automattic, proceed to the Settings page and, under the Composing section, enable the Write posts or pages in plain-text Markdown syntax option.

After that, write Markdown syntax in your article, and Jetpack will interpret the syntax and convert the elements to HTML in the published post.

Using a Static Website Generator

Static website generators are tools that create static HTML files from provided content files. Static sites are manually pre-built by the user, offering fast loading times and enhanced security.

Let’s explore how to use the two most popular software in this category.

Jekyll

Begin by installing Ruby (since Jekyll is a ruby Gem). In my Linux system I used the following command to install all the necessary packages:

sudo dnf install ruby ruby-devel openssl-devel redhat-rpm-config gcc-c++ @development-tools

Then install Jekyll:

gem install bundler jekyll

You can now create your first local blog with this command:

jekyll new myblog

Apply basic configuration to the blog by editing the _config.yml file located in the main blog folder. Here, you can set blog meta information like title, description, base URL, etc.

title: My Blog
description: My personal blog built with Jekyll
baseurl: "/"

To start creating your blog, add one or more Markdown files in the _posts folder and include Front Matter metadata in each file:

---
layout: post
title:  "My First Post"
date:   2024-09-04 12:00:00
categories: blog
---

## Example Heading

Example content.

* Item 1
* Item 2
* Item 3

Build the site:

bundle exec jekyll serve

After this command, the static site will be generated in the _site folder. A local URL will also be provided to see your site hosted locally.

Note that to generate the build files, you must repeat this command each time you add new blog posts or make configuration changes.

For more information on Jekyll, please see the official documentation. Information on the installation prerequisites is available here.

Hugo

Hugo is a static site generator written in the Go Programming Language. It’s commonly used in large websites for its fast build time.

To install it on Windows, download the executable from Hugo’s GitHub releases page and add it to your PATH.

With Linux, the installation process depends on the distribution. In my testing environment, I simply used this command:

dnf install hugo

Create a new site with this command:

hugo new site myblog

Make a new post with this instruction:

hugo new posts/my-first-post.md

Then, visit the main folder of the blog and build the site using the command:

hugo server

This last command generates your website in the public directory:

hugo

You can then deploy these static files to any web server using your favorite method.