Introduction

There are many tools for converting markdown files to HTML files, and I will introduce my personal top three.

Since it can automatically generate Table of Content and set up side navigation, I find it especially useful for creating documents and instruction manuals for websites I have built.

I can' t live without these tools, as I can now easily create things with markdown that I used to create with Word or PowerPoint, etc.

My 3 Best Tools

The following three are my best.
There is no superiority or inferiority among these three, but each has its own wonderful points.

  • StackEdit
  • Pandoc
  • Docusaurus

About StackEdit

Overview and Features

StackEdit is an open source markdown editor that runs in a browser.

In addition to being an editor, it has a rich GUI menu, so it is the easiest of the three tools to use.

Official Site
StackEdit – In-browser Markdown editor

Editor URL
StackEdit


Since it is built as a PWA, you can install it on your PC and use it, and it also works offline.

I often use StackEdit for text-only documents or documents that place image files from external sites.
If I want to place images from my local computer, I use the two tools described later.

The features of StackEdit and the things I like about it are as follows.

  • Intuitive to use, so there is less learning cost
  • As a PWA, it can be installed on a PC and called from Windows menu.
  • Works offline.
  • Files can be organized into folders (information is stored in the browser's local storage).
  • It has a publish function that allows you to add files to your WordPress account or save them to storage such as Dropbox or Google Drive.
  • It can generate an HTML file with a automatically generated Table of Content that follows the user's scrolling.
  • The output HTML file can stand alone as a web page.
  • The output HTML file can be viewed on a local machine (no need for a web server).
  • Multiple workspaces can be set (for example, you can switch between multiple Google Drives).
  • Editing history is saved.

Screenshot of main functions

Overview of each section


The left side is the input panel, and the information is previewed on the right side. The left side navigation also allows you to organize your files.

The right side navigation gives you access to various menus.

Publish feature


It has a publish function that adds files to various services by linking to WordPress, Dropbox, and Google accounts, etc. I haven't used the publish feature to WordPress, but it sounds useful.

I often use this publish function for saving files to storage.

Exporting HTML files



Select "Styled HTML with TOC" at the bottom to export an HTML file with a table of contents that follows your scroll.
Anchor links have also been applied to the table of contents.


Cases where StackEdit is not suitable

I don't use StackEdit when placing images of my local PC in the document.

In StackEdit, you can insert images using Markdown syntax, or you can insert images from the menu.

However, you need to insert images in URL format.
If you enter the file path to the image on your local PC, you will not be able to preview it in StackEdit.

In this case, I use Pandoc or Docusaurus.

The reason for this is that when I use these two tools, I basically create markdown files with code editors such as Visual Studio Code. Using a code editor plugin completes the paths to images and video files in the local environment, so it takes less time than writing markdowns in StackEdit.

About Pandoc

Overview and Features

Pandoc is an open-source document converter that operates via CLI.

Not only can it convert markdown files to HTML format, but it also supports various document formats such as Microsoft Word, XML, and Wiki, etc.

Official Site
Pandoc - About pandoc

Pandoc is operated by commands, but if you specialize in exporting markdown files to HTML files for documentation, you only need to learn one command.

Also, in the HTML file output by Pandoc, only simple CSS is applied by default, but by using templates available on GitHub, you can create a page with beautiful styles applied.

I use Pandoc when I want to insert images and videos stored on my local machine into markdown files.

I often organize the images and videos in an images directory, load them into a markdown file, and use Pandoc to output the HTML file.

Then I often send the entire folder containing the images directory to the person I want to provide the material to.

Docusaurus, which will be discussed later, provides very powerful features for building multi-page documentation sites, but the exported files cannot be viewed without a web server, so Pandoc is easier to use if the files are to be viewed on each user's local machine.

The features of Pandoc and what I like about it are as follows

  • It is used with CLI
  • Supports any document file format
  • You can create your own templates for the output files.
  • You can also use templates published by others.
  • The output HTML file can be used as a web page on its own.
  • You can adjust the design by adding CSS (same with StackEdit, but by adding CSS to the template, you don't have to add it every time).
  • The output HTML file can be viewed on a local machine (no need for a web server).

How to install

For Windows, the easiest way is to use the installer. A ZIP file containing the binaries is also provided.

Both can be downloaded from the following link:
Release pandoc 2.14.1 · jgm/pandoc

To check if the installation is complete, launch a terminal and run the following command.

pandoc -v

If the version of Pandoc is displayed, the installation is complete.

If you want to know more detailed information, please check the official website below.

Official site
Installing pandoc

Download the template

In my case, I often use easy-pandoc-templates, which is published on GitHub by Ryan Grose, a data engineer, under the GNU General Public License v3.0.

The template files can be downloaded from the following link.

easy-pandoc-templates
ryangrose/easy-pandoc-templates: A collection of portable pandoc templates with no dependencies

Convert a markdown file

In this section, I' ll show you how to convert a markdown file to HTML using the "easy-pandoc-templates" downloaded above.

First, the directory structure should look like the following.

your-directory
├── your-markdown.md
└── easy-pandoc-templates-master

Please keep the downloaded files in the easy-pandoc-templates-master folder as they are.

Next, open a terminal window and move to the directory where the markdown files are located.

Then, run the following command.

pandoc -s --toc --template=easy-pandoc-templates-master/html/elegant_bootstrap_menu.html your-markdown.md -o your-markdown.html

The following is the description of the command.

  • -s : The option to create a standalone page. This will generate a standalone HTML page as an HTML document with head tags and so on.
  • -toc : The option to generate a Table of Content.
  • --template : Specify the URL or file path of the template file. Here, we will use the template elegant_bootstrap_menu.html.
  • your-markdown.md : Specify the name of the markdown file to be converted.
  • -o your-markdown.html : Specify the name of the output file.

This command will output an HTML file in the working directory you have moved to.

A table of contents that follows the scrolling will be generated on the left side of the page, as shown below.


By adding CSS and JavaScript to elegant_bootstrap_menu.html, you can also adjust the appearance and apply smooth scrolling.

About Docusaurus

Overview and Features

Docusaurus is a document site creation tool developed by Facebook.


While StackEdit is a markdown editor that can output HTML files, and Pandoc is a command-based document conversion tool, Docusaurus is a Static Site Generator.

Therefore, Docusaurus is more useful for creating multi-page websites than for creating a single HTML page.

The features of Docusaurus and what I like about it are as follows.

  • Static Site Generator.
  • Good at building documentation sites.
  • It can convert markdown files into static sites.
  • It supports React.
  • It has features for multilingual sites.
  • It has a document version control feature.
  • Supports a site search function (Algolia documentation search)
  • Has a deployment function

Although it is a tool for building document sites, it can also be used to create independent pages such as home page, company profiles (like "page" in WordPress) , and blog posts.

In my case, Docusaurus is very useful for creating manuals with a large number of pages.

However, Docusaurus requires a web server to browse the static sites it builds.
In other words, you cannot drag and drop HTML files on your local machine into the browser and browse them with file:// URL format (if anyone knows how to do this, please let me know via my twitter @ktsmz!).

Therefore, if you do not want your site to be public, you need to restrict access by IP address, etc.

This topic is discussed in the following GitHub issue.
Support Relative Path · Issue #448 · facebook/docusaurus

Usage of Docusaurus

The usage of Docusaurus is too much to explain here, so please see the following article.

Related article
Create a site with markdown - Docusaurus Tutorial


Author Info
Profile Icon

Director of web and marketing

Kota Shimizu

I've been working in web, video, and magazine production fields, experienced planning, design, photography, coding, marketing, and business improvement. I'm an omnivorous director who can handle anything in a widely.