Markdown Editor — Tips & Tricks

Back to the overview: Markdown Editor · Open the tool live: www.jpkc.com/tools/md/

The manual describes every function, the examples show the workflows. This page is about what both assume but rarely state: how to make the live preview really work for you, which rendering quirks would otherwise surprise you, and how to wire the editor up with other JPKCom tools. Button names are given exactly as they appear in the interface.

Use the live preview smartly

Synchronized scrolling is your proofreading mode. In long documents, the coupled columns always show the rendered state of the spot you're typing at. Turn it off with Toggle synchronized scrolling only when you deliberately want to look at a different place in the source than in the preview.
Pick the scroll mode to suit the document. The default, Line-accurate, keeps the preview pinned to the block you're editing — ideal for texts with images, diagrams, and tables, because the preview no longer drifts away. If it bothers you that it speeds up briefly over a large image, switch Synchronized scrolling in Settings to Proportional (classic, evenly paced); that runs evenly and suits plain prose well.
Switch the view to match the phase. For structuring and typing, Editor + Preview is ideal. For writing in one stretch, Editor only gives you room; for a final read-through or presenting, use Preview only or the fullscreen Preview. On a phone, switch with the Markdown and Preview tabs.
The table-of-contents panel is jump navigation and a length gauge. Table of Contents is built from your headings — in long documents you jump through it faster than scrolling, and the heading lands at the top of the editor. The number next to each entry is the section's word count, so you can see at a glance which chapter is getting out of hand. For the total length, check the status line below the editor: it shows words and the estimated reading time.
Pick the reading theme to match the target medium. The preview has Dark, Light, and Sepia. Dark is comfortable for on-screen work; if you want to gauge how the document looks printed or as a light PDF, switch to Light first.

Know the rendering pitfalls

The editor renders with markdown-it plus a few enabled options — convenient, but they deviate from strict CommonMark. Knowing this saves surprises:

breaks is on: every single line break becomes a <br>. That's pleasant while typing, but it deviates from GFM/CommonMark, where a single break within the same paragraph does not create a line break. If you later use your Markdown somewhere that does not set breaks (many static site generators, GitHub in body text), the break will look different there. When in doubt, separate paragraphs with a blank line so it renders the same everywhere.
The typographer substitutes automatically. Straight quotes become curly, -- becomes an en dash, --- an em dash, ... an ellipsis. But --- alone on a line is a horizontal rule — not every run of dashes becomes a dash. If you literally need three hyphens in the text, escape them.
html is on: embedded HTML is rendered — filtered. You can mix in HTML, a <details> element for instance. The output passes through DOMPurify first, though: <script> tags, event handlers, and other executable parts disappear, including from files loaded via URL. So if part of your HTML is missing from the preview, the filter classified it as dangerous. It stays in the source and is saved unchanged with Save as Markdown.
KaTeX uses dollar delimiters. $…$ is inline math, $$…$$ a math block. A single $ in body text (prices, shell variables) can therefore be misread as the start of a formula — escape it as \$ if the preview misbehaves.
Mermaid needs the exact language tag. Only a code block with mermaid as its language becomes a diagram; a typo in the language line turns it into an ordinary code block — without colors, because highlight.js doesn't know the language.
linkify auto-links bare URLs — even without a protocol. An address written in the text becomes a link, even without […](…) syntax, and even a bare example.com gets linked. Usually handy — if you want to show a URL, or a file name that looks like a domain, as text only, put it in inline code.
Front matter is recognized, but only at the very top. A --- block (YAML) or +++ block (TOML) starting on line 1 shows up in the preview as a set-off code block — handy for blog posts that a static site generator will process later; the Blog Post template creates exactly such a block. Put even a single blank line in front of it, and markdown-it reads the --- as a horizontal rule or a Setext heading.

Saving, loading, discarding — without losing data

Auto-save is convenient but browser-bound. Your text is automatically kept in this browser's localStorage (see the manual). Another browser, another device, or a cleared browser store won't know it. For anything you want to keep, the rule is: Save as Markdown (Ctrl+S) once.
Replacing can be undone. New document, Clear document, templates, opened files, and Load from URL… replace the editor content entirely. Before they do, though, the editor takes a snapshot automatically, and Ctrl+Z undoes the replacement. You get the snapshot back via File → Snapshots… → Restore, even after a reload.
Take a named snapshot before major rework. Automatic snapshots are called "… — before clearing" or similar and are the first to go once the limit of 20 is reached. A state you definitely want to return to is best saved under your own name with Save current document.
New document isn't a blank page. It loads the welcome text with examples of the most important syntax elements — useful as a reference. For an empty page, use Clear document.
The status badge is your save indicator. When it turns green in the editor header, the current state is in localStorage. If it turns red, storage is full or blocked — often after several pasted images that sit in the text as Base64. In that case, save the document as a file and link large images rather than embedding them.

Export cleanly

For PDF/HTML the preview theme doesn't matter. On Save as PDF and Save as HTML export, code blocks and Mermaid diagrams are automatically switched to a light theme so they're legible on a white background — regardless of whether you're currently viewing Dark, Light, or Sepia.
Save as HTML delivers a standalone document — almost. Layout, code highlighting, and the KaTeX CSS are embedded, so the file needs no external stylesheets. Two things do come from the network when it's opened, though: the fonts for formulas (from the JPKCom server) and images you included by URL. If the file has to be complete offline, embed images as data URIs via drag & drop.
The first heading names the file. Whether .md, .html, or .pdf: the file name is derived from the first heading (# Release Notes 2.0 → release-notes-2-0.pdf). Without one, the tool uses the first line of text, and only if that yields no name is the file called document.*. A clean H1 saves you the renaming.
Copy as formatted text for email and office, Copy as HTML for source code. To get the result into an email, Word, or Google Docs, use Copy as formatted text — the target application receives rendered HTML, a plain text field the Markdown source. Copy as HTML, by contrast, copies the complete HTML document with <head> and styles as text; that's what you want when you need to process HTML source further. For a CMS field that expects only the content, take the part between <body> and </body>.

Format and tidy up faster

Buttons toggle. A second click on Bold, Italic & co. removes the markers again, as long as the text is selected. With headings, a different level replaces the old one; with lists, a different type replaces the existing one — so there's no need to delete ## or - by hand first.
Just paste tables from your spreadsheet. Paste cells from Excel or Google Sheets into the editor with Ctrl+V, and they become an aligned Markdown table. CSV data with commas or semicolons goes into the Insert table dialog under …or paste data.
Tidy up Markdown before you commit. File → Tidy up Markdown aligns every table, strips trailing spaces and duplicate blank lines — the rendered output stays identical, and the contents of backtick or tilde code blocks and the front matter remain untouched. That keeps your Git diffs clean.
Emojis via the colon. Type : and the first few letters (:thu), and a suggestion list pops up. What gets inserted is the shortcode (:thumbsup:), not the character — the source stays plain ASCII, the preview shows the emoji. A picker with search is also available in the toolbar.
Toolbar without a mouse. Tab takes you into the toolbar, the arrow keys move from button to button, Enter triggers. The toolbar is a single tab stop, so the next Tab takes you right back out.

Combining with other JPKCom tools

Prefer visual over syntax? The WYSIWYG Editor is the closest relative: a rich-text HTML editor based on TipTap with Markdown import and export. You can move content back and forth between the two tools — structure it in the Markdown Editor, polish it visually in the WYSIWYG tool, or the other way around.
Inspect and tidy exported HTML. The markup produced by Copy as HTML/Save as HTML can be viewed with syntax highlighting in the Source Viewer and formatted as needed with Beautify.
Markdown is the AI format. When you provide content for AI systems, Markdown is the lowest-noise format. Build a matching, valid llms.txt for your site with the llms.txt Generator.

More context: the overview for the big picture, the manual for every function, and the examples for the step-by-step workflows. You can try it all directly in the tool.