A markdown editor is an application that allows you to write and format documents using a markup language called Markdown, then render those files in web-ready formats such as HTML or PDF. Markdown itself sits between plain text and a full word processor, converting your markup into something a browser can read.
When evaluating a markdown editor, consider its benefits, cost, ease of use, and host platform. These considerations are just as important when choosing any tool for authoring HTML or CSS.
One known practical friction point is that sharing a markdown file with someone else may require them to have a markdown editor (or at least a viewer) that will render the plain-text formatting. This means it’s hard to share Markdown files directly with others, but not impossible.
Markdown editors also must meet different needs depending on who is writing and how they want to share what they’ve written. If it’s a solo writer, looking for a long-form Markdown document — such as this blog post you’re reading — a cross-platform individual app might be best suited to their workflow. A developer team would need one that could fit within their existing development environment, and perhaps even integrate with version control systems like GitHub. In both cases, however, a robust review system that lets developers comment inline and collaborate efficiently will be a plus.
In short, a good markdown editor should allow you to write as fast as you would in a local application, while still allowing your document to be stored securely online, shared with teammates, and exported cleanly to other media.
If you’ve used Word or Google Docs, you’ll probably be familiar with the idea of formatting documents via menus, buttons, drop-down selections, or keyboard shortcuts. You’ll know what bold, italic, headers, and lists look like. Markdown takes all of these options out of the menu and puts them back in your hands — more or less.
It turns out there’s nothing magical about markdown. All it does is take plain text and mark it up so that the final output (usually in HTML) will display accordingly.
For example, to create a header in markdown, use hash symbols before the text. For instance:
Header 1
Header 2
Header 3
And so on. To make a section of text bold, wrap it in double asterisks:
This is bold text.
To italicize, surround the text with single asterisks:
This is italicized text.
And so on.
Why do we care? Well, markdown doesn’t require any special programs or apps to open and edit a markdown file. You can write and edit a markdown file with any simple text editor (e.g., Notepad, TextEdit). The only difference between a markdown file and a simple .txt file is that markdown files usually include formatting commands that dictate how the document should be displayed.
The same is true of Microsoft Office files, Apple Pages, OpenDocument, and other proprietary formats. Those files require specific apps, which don’t always exist for every operating system, to open and modify. Markdown does not.
The result is a lightweight, easy-to-edit format that works across platforms and doesn’t lock you into any particular software or vendor.
That said, you don’t need to go through life without some kind of formatting tools. You’ll need a markdown editor or viewer to render that formatting in any way you choose.
We recommend several editors depending on your use case.
There are few writers who enjoy working inside the confines of Microsoft Word. The experience is clunky, inefficient, and often time-consuming. We believe in the power of the plain-text editor, though, and prefer our workspaces clean, uncluttered, and efficient. There are two exceptions: the occasional formatted document that requires some advanced features, like tables, or code blocks.
Our personal preference is Ghostwriter, which gives us the ability to work in our preferred plain-text editor, VS Code, while also providing powerful editing capabilities like syntax checking, outlining, and automatic generation of Table of Contents links. But if you’d rather work in an integrated solution, Zettlr offers the robustest markdown option, albeit at a price.
Ghostwriter provides additional functionality, such as the ability to export to various formats and generate an outline. We prefer it because it allows us to work where we are most comfortable: inside of VS Code. It also makes sense for writers and researchers who want to build rich outlines, reference external sources, and otherwise work outside of a dedicated word processor. We also use it to draft blog posts here at TechHive before transferring them to WordPress.
Other options worth considering are Typora, which has a minimalist interface and no frills but also no real restrictions; and MarkText, which offers Mac, Windows, and Linux versions. MarkText can export to PDF and HTML and includes a split-pane view that shows the rendered HTML side by side. It also supports the preview of Markdown files inside of a browser, along with a variety of other helpful features.
Developers face a different challenge than writers. When a developer writes a Markdown file, he or she wants to ensure that their Markdown is being rendered properly within the context of a larger body of work. That could mean exporting to HTML to embed in a website, or publishing a technical article on GitHub Pages.
But for developers, Markdown isn’t just a way to present documentation — it’s also part of the process. Developers use Markdown to document functions, parameters, and API calls, and many rely on tools like Jekyll, Pelican, Hugo, or Sphinx to turn those markdown files into actual websites. Because of this, developers must rely on tools that can parse their markdown files, convert them to HTML or another output format, and publish them quickly. They also need tools that let them keep track of their own progress, whether through version control systems like Git, or tools like GitHub or Bitbucket, or cloud-based services like Netlify or Firebase.
Because of all of this, the most important feature a markdown editor must offer is the ability to read and write raw markdown. While there are plenty of markdown editors, they generally fall into one of two categories: ones that simply render a markdown file in HTML or PDF, and those that support a richer ecosystem around markdown files.
For developers, it really depends on what they’re building. Many modern projects involve GitHub or other collaborative environments, and they may not necessarily need a full-blown markdown editor, especially if they already have one in place. Others may find value in the ability to check off tasks or share drafts with others.
However, without inline review tools, such as comments, suggestions, or edits, a team falls back on other mechanisms to communicate: email, pasting screenshots from a browser, or other methods that aren’t ideal for tracking feedback. Without the ability to see what changes others are making to their project, they can’t truly collaborate. And wiki-like environments lock content into proprietary formats, preventing reuse elsewhere.
So, if your company uses GitHub or another similar service, you’re well on your way to finding a markdown editor. You can even use a markdown editor like Typora, or use the native Markdown features within Visual Studio Code.
APIs are a common use case for Markdown. Documentation writers may use Markdown to provide a set of code examples for each endpoint, along with detailed descriptions of parameters and responses. They can also leverage parameter tables, and ensure that the formatting remains consistent across all endpoints. This consistency helps ensure that developers understand exactly what the endpoint expects and how it should respond.
Another scenario is when someone creates a 30-minute video walkthrough on how to accomplish a certain task, then converts it into a concise, searchable guide. Developers and writers can reference this guide daily, without disrupting their workflow.