If you write documentation, there’s a good chance that you’re writing them in Markdown. If not, then you’re missing out. But, this article is not about convincing you to use Markdown. Instead, to teach you the many ways to convert Markdown to HTML.
If Markdown is so great, why is there are need to convert it to HTML? Remember that Markdown is the code (the Markdown syntax) behind how the document is formatted. When it’s time to view the Markdown document, you are still looking at its HTML rendering.
Some reasons when you will need to convert Markdown to HTML include:
- A Markdown file on its own is just code. In fact, it’s called a markup language. To view the document the way the Markdown formatting intended, it has to be in HTML.
- If you have a static website, sometimes it is quicker to write a web page using Markdown. Then, convert your Markdown page to HTML, which you can upload to your website.
- If you share raw Markdown documents with non-technical people, it would mean nothing to them.
- Suppose your boss asks you to share documentation of something. In that case, a raw Markdown document is not exactly the most appropriate format.
If you’re still interested, keep on reading. You’ll learn quick ways to convert Markdown to HTML, and even some methods that are more involved.
Prerequisites
If you plan to follow along with the examples in this article, you need to have:
- A Markdown document for conversion. You can create your own or download this sample_readme.md file.
- Other tools will be required only in individual sections. You will only need them if you choose to do the examples.
Using Command-Line Tools To Convert Markdown to HTML
These command-line tools are useful if you’re converting multiple Markdown documents, running server-side processes, or scripting. In this section, you will learn about some command-line tools used to convert Markdown to HTML and how to use them.
PowerShell
PowerShell 6.1 introduced the cmdlet ConvertFrom-Markdown. This cmdlet converts the contents of a Markdown file into a Markdowninfo object in PowerShell. The latest release as of this writing is PowerShell 7.0.3.
Suppose the Markdown file to convert is named sample_readme.md. Using the command below converts the contents of the file and save the result to a variable named $md.
$md = ConvertFrom-Markdown -Path .\sample_readme.mdThen, $md variable becomes a MarkdownInfo object whose HTML property contains the HTML converted value of the Markdown file.
The command below exports the converted HTML value to a new HTML document with name .\sample_readme.html.
$md.Html | Out-File -Encoding utf8 .\sample_readme.htmlAnd when you open the .\sample_readme.html using your browser, the content will be displayed similar to the image below.
Pandoc
Pandoc is a universal document converter used to convert to and from many different formats, including Markdown to HTML. You can download Pandoc and view the installation instructions for different systems from this link. In this example, Pandoc is installed using Chocolatey.
choco install pandocThe image below shows Pandoc being installed using Chocolatey.
When you’ve installed Pandoc, you can open your command interpreter, such as CMD, and use the pandoc command. Suppose the Markdown document to convert is sample_readme.md. Using the command below converts the Markdown contents of sample_readme.md. The converted document is then saved to sample_readme.html.
pandoc sample_readme.md -t html -o sample_readme.htmlThe screenshot below shows the result of running the command above.
The image below shows the HTML output after using Pandoc to export Markdown to HTML. By default, there are no fancy formatting, and the appearance looks plain.
There are many more options available in Pandoc that can significantly alter the output, such as adding a title to the resulting HTML file and other metadata values. Learn more about what Pandoc can do by checking out their demo page.
Showdown
Showdown is another Markdown to HTML converter written in Javascript. This conversion tool can be used for client-side or server-side operations. Showdown requires Node.js to be installed on the computer where you plan to use it.
Once Node.js is installed, the Showdown CLI tool can be installed using the command below. You can run this command in PowerShell or CMD on Windows.
npm install showdown -gYou should see an installation process similar to the screenshot below.
After Showdown is installed, using the command below converts the sample_readme.md to sample_readme.html.
showdown makehtml -i .\sample_readme.md -o .\sample_readme.htmlThe above command should give you a result similar to the output below.
Using GUI Editors To Convert Markdown to HTML
A Markdown document is edited as plain-text, which means that almost any text editor can create them. However, not all editors have the capacity to export or convert Markdown documents to HTML.
In this section, you’ll learn about some of the popular GUI editors, online and offline, capable of converting Markdown contents to HTML.
Notepad++
Notepad++ is a popular, free editor with several plugins available that you can install to extend its capabilities. One of these plugins is the MarkdownViewer++, which adds the feature to render and export Markdown contents to HTML.
You can install the MarkdownViewer++ plugin by going to Plugins —> Plugins Admin. Once inside the Plugins Admin window, select the MarkdownViewer++ and click on Install. When prompted, click Yes. Notepad++ will restart automatically.
After the plugin is installed, open the Markdown file and click on the MarkdownViewer++ button. The pane where the HTML rendering of the Markdown file should show up. To export the content, click on Export as —> HTML. Then, save the file in your chosen location.
Below you can see that the HTML output is plain and has no style formatting.
Atom
Another great editor that supports many languages is Atom. Atom also comes with packages, that when installed, extend its features further. One of these packages is the markdown-preview, which gives Atom the ability to save markdown content to HTML. Best of all, markdown-preview is already installed by default!
The first step to convert Markdown to HTML is to open your Markdown document in Atom. Then toggle the Markdown preview by pressing the CTRL+SHIFT+M keyboard shortcut. Another way to toggle the Markdown preview is from Packages —> Markdown Preview —> Toggle Preview.
Once the preview pane shows up, right-click on the preview and click Save as HTML, and save the file in your preferred folder. Refer to the demonstration below.
Below, you can see what the HTML formatted file looks like when exported using Atom. You might recognize that the appearance is similar to how GitHub displays Markdown contents.
Visual Studio Code
If you write code, then there’s a good chance that you are already using Visual Studio Code to write them. Even better if you do your documentation in Markdown, which means there’s only one more thing you need to convert Markdown to HTML. That’s the Markdown All in One extension.
While in Visual Studio Code, to install the Markdown All in One extension, type in this command below in the terminal.
code --install-extension yzhang.markdown-all-in-oneThe demonstration below shows the result of running the command above.
Once the extension is installed, you can export all the Markdown documents in the loaded folder, or just the current Markdown document. First, open the Command Palette by pressing CTRL+SHIFT+P. Then, start typing in “Markdown” and click on the Markdown All in One: Print current document to HTML command.
The image below shows how the HTML formatting looks like after exporting the Markdown document. As you can see, the design appears a lot different than all the previous ones.
Typora
Typora is what you would call a What You See Is What You Get or (WYSIWYG) Markdown editor for Windows. What’s more, Typora supports theming, which means that you can apply pre-defined themes to your Markdown documents.
For example, the image below shows that the Markdown file is loaded in Typora with the theme Newsprint applied. When you export the Markdown contents to HTML, the output should look exactly as when you’re editing it in Typora.
To convert Markdown to HTML using Typora, click File —> Export —> HTML. Then save the file in your preferred location.
The image below shows that the HTML output looks exactly as how the Markdown is displayed inside Typora.
Dillinger
So far, all you’ve learned about are tools to convert Markdown to HTML used offline. Which means you need to install them before you can use those tools. Apart from those, there are online tools available to do the job.
Dillinger is one example of an online Markdown editor that can export content to HTML. To use Dillinger, go to its website at https://dillinger.io/. Once on the website, you can upload your Markdown file from your computer or other cloud sources like Dropbox and Github.
Once the Markdown document is loaded in Dillinger, click on Export As —> Styled HTML. Then, the HTML file will be downloaded to your computer.
Other Markdown to HTML Conversion Tools
Apart from what you’re already learned in this article, there are many more tools used to convert Markdown to HTML. Here are some that you may want to consider.
Web Tools
Static Site Generators
Conclusion
There are many tools to convert Markdown to HTML. Some tools are readily accessible online, and some need to be installed locally on your computer. All these tools have the same goal, but not all of them are created equal – so to speak.
It is up to you to find out which one of these tools works best for you. Whether you’re converting one Markdown file or a batch of Markdown files are once, there’s a tool that’s appropriate for you.
