visualmd

visualmd

A Markdown editor that shows you the rendered document while you type it: plain Markdown source in one pane, a live preview in the other. It is a single binary with no runtime dependencies — no browser, no Electron, no C toolchain — and it also converts Markdown to PDF from the command line, without opening a window.

Installation

$ CGO_ENABLED=0 go install modernc.org/visualmd@latest

CGO_ENABLED=0 is optional; it is there to show the whole thing builds without CGo. Builds and cross-compiles for Linux, macOS, Windows and FreeBSD on the usual architectures — see make build_all_targets.

Using it

$ visualmd [file.md]        # edit
$ visualmd -r [file.md]     # open in reader mode
$ visualmd -pdf file.md ... # convert to PDF and exit

The window has the Markdown palette and the configuration on the left, and the document on the right: the rendered Preview, the generated HTML source, and a Log of render timings and errors, above the editor.

Ctrl+D puts the editor and the preview side by side; Ctrl+R (or starting with -r) hides everything except the preview, for reading rather than writing.

The editor

Markdown syntax highlighting with a line-number gutter, in a fixed-width font so tables, indented code and list nesting line up. Fenced code blocks are dimmed as a whole, so a # comment inside a shell block does not masquerade as a heading. The Markdown palette inserts tables, lists, links, pictures and a stylesheet template, and wraps the selection in bold, italic, strikethrough, headings, inline code, code blocks or block quotes.

The preview

Rendered as you type, with the render coalesced so a burst of keystrokes costs one repaint. Tables, floats, flexbox and grid, backgrounds, borders and border-radius, images and SVG all render. Images load from a path next to the document or over http(s), and are cached. http(s) links open in the system browser; a link to a heading scrolls the preview there, and the arrows in the menu bar walk that history back and forward. Ctrl with +, - or 0 zooms.

Drag to select text — a double-click takes a word, Ctrl+A the whole page — and Ctrl+C or Edit | Copy puts it on the clipboard. A drag that starts on a link selects its text; a click on it still follows it. What is copied is the text as laid out, line by line, so a line's words keep their spaces and a back/forward broken at the slash comes back in one piece.

The configuration

The Configuration palette turns each of gomarkdown's 24 parser extensions and 20 HTML renderer flags on and off, and the preview re-renders immediately — tables, footnotes, definition lists, MathJax, Smartypants, heading IDs and the rest. Whatever is selected there is what Save As and the export buttons use.

Exporting

The <html> and <pdf> buttons in the Markdown palette, and Save As, write the document as HTML or PDF. A PDF gets real embedded text, clickable links and a heading outline you can navigate in a reader.

-pdf does the same without ever starting the GUI, so it works over ssh, in a container or from a Makefile:

$ visualmd -pdf notes.md          # writes ./notes.md.pdf
$ visualmd -pdf ch1.md ch2.md     # one PDF each, in the working directory
$ visualmd -pdf < in.md > out.pdf # or as a plain filter

What it will not do

Being clear about this is the point of this section:

• Selecting in the preview is by mouse, not by keyboard. There is no caret there to move with Shift+arrows, and a code block scrolled sideways keeps its highlight where the text was before the scroll. The editor holds the source and the HTML tab the markup, and both select like any text widget.
• No JavaScript. The preview renders HTML and CSS; nothing scripts.
• The renderer is a useful subset, not a browser. It covers CSS 1, CSS 2.1 and a good part of CSS 3 over HTML 5, which is comfortably more than Markdown generates — but a page that leans on the far corners of the platform will not come out right.
• Editor highlighting is approximate. It is regular expressions matched a line at a time, not a Markdown parser: *emphasis* is coloured, _emphasis_ is not, and anything that spans lines is out of reach.
• One document per window. There is no file tree, no tabs, no session, and clicking a link to another local file does not open it.
• No spell checking, no outline pane, no plugins, no collaborative editing.
• The Markdown dialect is gomarkdown's, with the extensions you choose.

How it is built

Three CGo-free pieces, all pure Go:

• modernc.org/tk9.0 — the Tcl/Tk GUI toolkit the window is made of, including its ctext and ntext extensions behind the editor.
• gomarkdown — Markdown to HTML.
• modernc.org/webview — the engine that lays out and paints the preview, and writes the PDF.

Gallery

License

BSD 3-Clause. See LICENSE.