Recommended Markdown Editors
Once the syntax is behind you, a practical question surfaces: which tool should you actually type into? This page is about that question, and its main conclusion is worth stating early. The editor only affects your writing experience, never the file. Whichever tool you choose, what lands on disk is a plain text file containing the same characters, and the syntax rules are identical everywhere. Pick on ergonomics and workflow, not on output.
That matters because it removes the anxiety that usually comes with this choice. You are not locking a project into a tool, and you are not making a decision that is expensive to reverse. Start with whatever you already have installed, and move on.
- VS Code: a source editor with plugins that turn it into a full Markdown environment.
- Typora: a dedicated writer that hides the syntax behind a clean page.
- Obsidian: a local knowledge base built around linked notes.
- Notion: a collaborative platform that imports and exports Markdown.
- Browser and online: GitHub, GitLab, and Gitee all edit and preview Markdown in the browser.
The useful way to compare them is along two axes: how much of the raw source the editor shows you, and whether the editor is organised around files or around a workspace.
| Editor | Type | Best for | Worth knowing |
|---|---|---|---|
| VS Code | Source editor plus plugins | Writing code and documentation together | Preview and navigation come from plugins |
| Typora | WYSIWYG | Long-form writing with minimal distraction | Extension syntax support is limited |
| Obsidian | Local knowledge base | Bidirectional links, cross-document notes | Custom syntax can drift from the common style |
| Notion and similar online tools | Collaboration platform | Team documents, editing from any device | Import and export can drop some syntax |
VS Code is the pragmatic choice when the writing sits next to the code. It ships with Markdown support out of the box, and the plugin ecosystem fills in the rest: Markdown All in One for table-of-contents generation and list editing, Paste Image for turning a clipboard screenshot into a file plus a link, and Preview Enhanced for a richer preview with Mermaid diagrams and math. The trade-off is that the default experience is a plain editor, so you install a couple of extensions before it feels like a writing tool.
Typora optimises for the opposite thing: getting the syntax out of your way. It renders the formatting as you type, so you see a clean document rather than a wall of markers, and it hides the markers for the current line while you edit it. It is a commercial product with a one-time licence, and it deliberately supports a smaller set of extensions than the community tools.
Obsidian is a different category. It treats a folder of Markdown files as a knowledge base, with bidirectional links between notes and a graph view that makes the connections visible. If your writing is a web of interlocking ideas rather than a sequence of documents, that is exactly the tool. If you are writing a specification with a strict order, the extra machinery mostly sits idle.
Notion and its competitors come at the problem from the collaboration side. Editing is live for everyone, comments and version history are built in, and Markdown can be imported and exported. The cost is that the platform owns the file: the Markdown you get on export is a conversion of what Notion stored, so a few constructs, particularly exotic tables or custom callouts, may not survive the round trip.
Browser editing on GitHub, GitLab, and Gitee is worth using even if your local editor is your home, because it is the fastest path from “I have a change” to “the change is visible to the team”. The in-browser preview is accurate for the dialect those platforms support, which is GFM.
Most editors offer two ways of seeing the same file, and the choice between them is the one real trade-off in this page.
A source view shows the raw characters. Its advantage is that nothing is hidden, so a stray space or a missing blank line is visible immediately rather than being inferred from a rendering that looks subtly wrong. Its cost is that you read markup while you write, which is slower for long prose.
A live preview shows the rendered result. Its advantage is that the structure is obvious while you are writing, which makes it much harder to accidentally break a list. Its cost is exactly the mirror image: when the preview looks wrong, the source view becomes the only way to find out why.
The practical advice is to use both, at different moments. Write in the live preview so the structure stays clear, then switch to the source view and read the file once before you commit it. Most “the rendering is off” problems are visible the moment you look at the source, and they are almost always a missing blank line or a mismatched marker.
Here is the same file in both views. The source:
## Installation
- Run `npm install` to install dependencies.And the preview:
<h2>Installation</h2>
<ul>
<li>Run <code>npm install</code> to install dependencies.</li>
</ul>Both views point at one file on disk. The preview is not a separate document that you might drift out of sync with; it is a presentation of the source you are editing.
Extensions cover the features the core syntax does not include: automatic tables of contents, syntax highlighting, formulas through KaTeX or MathJax, task lists, and diagrams written in Mermaid.
The one that saves the most time in practice is image pasting. Copy a screenshot, paste it into the editor, and the editor writes the image file to disk and inserts a link to it. The source ends up with a single line:
Which renders as:
<p><img src="./images/arch.png" alt="Architecture diagram"></p>All you have to check is that the file really landed in the folder you expected. No tag needs to be written by hand, and if the path is wrong the fix is one line of source.
- Writing code or documentation: VS Code.
- Pure writing, especially long documents: Typora or Obsidian.
- Team collaboration: Notion or a similar collaborative tool.
Rather than agonise over that list, confirm three capabilities in whatever you pick, because they cover most of what makes writing in Markdown pleasant or painful:
- Live preview, so the structure is visible while you write.
- Automatic table of contents, so a long document does not need its outline maintained by hand.
- Image pasting, so screenshots do not turn into a file-management exercise.
A tool that does all three will not block you in daily use. Everything else is a preference, and preferences are cheap to change.
No editor will correct your syntax for you. A preview panel shows the parse result, not a validation result: one extra space after a marker and the preview silently loses a line break, and most editors say nothing about it. Checking the source view periodically is more effective than buying a more expensive editor, because it removes the layer where the mistake would otherwise hide.
In any editor you have available, create a new file and type the two lines below. Then switch to the source view and check them:
## Installation
- Run `npm install`State what you should see in each view, and list the two most common reasons the preview would fail to show the intended result.
Approach:
This exercise checks that the source view and the preview agree, and that you know which layer to trust when they do not. The source view must show the marker characters themselves; if the preview does not reflect them, the markers were not typed as Markdown markers. That distinction decides whether the problem is in the file or in the tool.
Steps:
- Create a new file and type two lines: a heading line, then a list item with an inline command.
- Switch to the source view and confirm that the hash, the backticks, and the dash are all visible as ordinary characters. This is the defining property of the source view: nothing is hidden.
- Check the preview. The heading should appear as a heading, the command should be set in a monospace font, and the second line should be indented as a list item.
- If the preview is wrong, check the two usual causes: the markers were typed with a non-English input method and came out as full-width punctuation instead of ASCII, or a space was added or omitted after a marker.
Answer:
In the source view you should see the literal characters #, the backticks, and the dash, because the source view shows the file exactly as it is stored. In the preview you should see a heading, a monospaced npm install, and an indented list item.
If the preview does not show those, the markers were not recognised. The two most common causes are using a non-English input method, which produces full-width punctuation where the parser expects ASCII characters, and a missing or extra space after a marker. In both cases the source view reveals the problem immediately, which is why reading the source before committing is worth the few seconds it takes.
You should now be able to place the main editors on two axes, what they show you and whether they are organised around files or around a workspace, and explain the trade-off between a source view and a live preview. You should be able to pick a tool by confirming three capabilities: live preview, an automatic table of contents, and image pasting. And you should be able to say plainly that the choice affects your workflow and not your output. Next, it is time to stop reading about the syntax and start typing it.