MarkHippo user guide

MarkHippo is a markdown viewer and editor. You write markdown on the left and the rendered document appears on the right. It reads markdown with its own parser, which covers all of CommonMark 0.31.2 and passes every one of the specification's 652 examples.

Writing and the preview

Type in the left pane. The source is coloured as you go: headings, emphasis, links, code, quotes and list markers each get their own colour, and the markup characters themselves (**, [ ], backticks) are dimmed. The colours catch up a moment after you pause; the preview a second after you stop typing. Neither runs on every keystroke, so both stay quick even on long documents, and in a long document only the blocks around your edit are parsed again.

The colours and the preview both show exactly what the parser understood. A # turns heading-coloured the moment it makes a heading, and if you leave a ``` code fence unclosed, everything below it turns into code, in the editor as well as the preview. That makes a missing fence easy to spot.

Code in a fenced block is coloured for its language, named after the opening fence (```python). MarkHippo knows JavaScript, TypeScript, JSON, YAML, Python, HTML and XML, CSS, shell, SQL, C, C++, C#, Java, Kotlin, Go, Rust, Swift, INI and TOML, Dockerfiles and diffs, and the usual short names for them (js, py, yml, sh…).

Drag the bar between the panes to resize them. You can also focus the bar and use the arrow keys. On a narrow screen the preview sits below the source.

The status bar shows how long the last parse took and whether the whole document or only part of it was parsed. It also shows the document's size and the cursor's line and column.

The mode button in the header switches between System (follow the operating system), Light and Dark.

Suggestions as you type

You don't need to remember markdown's syntax: MarkHippo offers it where it fits, in a list right at the cursor.

• Type / at the start of a line for headings, lists, quotes, code blocks, dividers and more. This works inside a quote or a list item too.
• Type / at the start of a word in the middle of a line for links, images, bold, italic, inline code and the like.
• Start a code fence (```) for the languages MarkHippo can colour.
• Type ][ after a link's text for the reference labels your document defines.
• Press Ctrl+Space (or Alt+/, ⌥+/ on a Mac, where Ctrl+Space usually switches keyboard language) anywhere to ask. With text selected, the suggestion wraps it: select a word, press Ctrl+Space and choose Bold.

Keep typing to narrow the list: /h2, /quote or /cb (the initials of Code block) all work. Use ↑ and ↓ to choose, Enter or Tab to insert, and Esc to close the list. Each suggestion shows the markdown it stands for, so the list doubles as a cheat sheet. After inserting, the part you'll want to change, such as a heading's text or a link's address, is selected, ready to type over.

Nothing is suggested inside code, and a / in the middle of a word or a web address never opens the list. When the list opens by itself on a code fence or after ][, nothing in it is chosen until you type or press an arrow key, so ``` followed by Enter is still just a new line.

Finding your way around

Three switches at the right of the status bar, at the bottom of the window:

• Sync scroll (on to begin with) keeps the editor and the preview at the same place: scroll either one and the other follows, heading for heading.
• Outline shows the document's headings in a panel on the left. Choose one to jump there in both panes. The section you're looking at is highlighted.
• Minimap shows the whole document in miniature beside the editor, in the editor's colours, with the part in view marked. Click or drag on it to go somewhere.

Headings get ids in the preview, so you can link to them: [see below](#getting-started) for a heading "Getting started". Type ](# and MarkHippo suggests the headings your document has.

Themes

Themes in the header opens the palettes. Each palette has a light and a dark version, and the mode (System, Light or Dark, in the dialog or the header button) picks between them. MarkHippo comes with Hippo, Catppuccin, Grey (the same greys as Rest Hippo) and High contrast. Choosing one applies it straight away.

To make your own, choose a palette and press Duplicate, or New to start from Hippo. Rename it and change any colour, in the Light and Dark tabs, with the colour picker or by typing a hex value. The page shows the tab you're editing as you go, and your theme is saved as you edit it. Built-in palettes can't be changed, only copied.

Beside each text colour is its contrast against the background it's read on. WCAG AA asks for 4.5:1; anything below that is shown in red. Every built-in palette meets it.

Export saves a theme as a .markhippo-theme.json file to keep or share, and Import… adds one, including Rest Hippo's theme files. Your themes live in this browser, like your document.

Images

Paste a screenshot or a copied picture into the editor, or drop image files on it, and they go into the document: at the cursor when pasted, where you let go when dropped. The picture's description (its alt text) is selected afterwards, so you can type one straight away; it is what screen readers say and what shows if the picture can't.

In the desktop app, once a document is saved, a picture you paste or drop is saved as a file in an assets folder beside it and linked by its path, such as ![login screen](assets/login-screen.png). The rest of this section is about the web, and about documents not yet saved.

On the web there is no folder beside your document for pictures to go in, so they go in the document itself, written out as data. To keep your text readable, that data is not put where the picture is but at the end of the document, as a numbered reference:

Here is the login screen: ![login screen][image-1]
…

[image-1]: data:image/png;base64,iVBORw0KGgo…

So a saved document is one file that carries its pictures with it, and shows them in any markdown viewer. To take a picture out, delete both its reference in the text and its line at the end.

PNG, JPEG, GIF and WebP pictures up to 1600 pixels wide and 1.5 MB go in exactly as they are. Bigger ones are scaled down to 1600 pixels wide, which is still sharp at the widest the preview shows a picture, so that documents stay small enough for the browser to keep. Other kinds the browser can read, such as SVG, are converted to PNG or JPEG. Animated GIFs always go in as they are.

If you paste something that comes with its own text as well as a picture, such as cells from a spreadsheet, the text is pasted, as usual.

Opening, saving and exporting

• Open… reads a markdown file from your computer. You can also drop a file anywhere on the page.
• Save downloads the markdown under the file name shown in the header.
• New starts an empty document.

Your document is kept in this browser and is still there the next time you open MarkHippo. Clearing the site's data removes it. Browsers keep only a few megabytes for a site, so if a document with many pictures grows too big to keep, the status bar says so: save it to keep a copy.

Export turns the rendered document into something else:

• Print or save as PDF… (Ctrl/⌘+P) prints the document alone, without the editor. To make a PDF, choose Save as PDF in the print dialog.
• HTML page saves a single .html file that opens in any browser, with its styles, math, diagrams and pasted pictures inside it.
• Rich text saves an .rtf file for Pages, Word, TextEdit or LibreOffice, with headings, emphasis, links, lists, tables, code and pasted PNG or JPEG pictures.
• Plain text saves a .txt file laid out to read: headings underlined, lists bulleted, links followed by their address.
• Copy as rich text copies the document, formatted, to paste into an email or another document.

Exports are always in your palette's light colours, as on paper, whatever the mode. Math and diagrams are drawn in the HTML page, the print and the copy; in RTF and plain text, math is its LaTeX and a diagram its Mermaid source.

The desktop app

MarkHippo is also a desktop app for macOS, Windows and Linux; its installers go on its page on Hippo Herd with its first release. It is this same page, in a window of its own, and it adds what a browser cannot do:

• Files. Open a .md file by double-clicking it, by dropping it on the window or the app's icon, or with File → Open…. Save writes it back in place, and Save As… makes a copy. The title bar shows when there are unsaved changes, and the app asks before closing or opening another document over them. The document you had open is opened again next time.
• Pictures beside the document. Once a document is saved, pasted or dropped pictures go in an assets folder beside it (see Images). Pictures a document already links to by a path, such as images/diagram.png, show in the preview too.
• Exports where you choose. Each export is saved through the usual Save dialog. Export → PDF makes a PDF directly, without the print dialog. Pictures beside the document go inside the HTML page, the RTF and the PDF.
• Your own plugins. See Your own plugins.
• A menu bar with the commands, the views (Outline, Minimap, Sync scroll) and the user guide, which opens in a window of its own.

The desktop app makes no network requests except for pictures a document shows from the web. Links open in your browser.

Keyboard

What markdown it understands

All of CommonMark:

• Headings: # Title through ######, or text underlined with === or ---.
• Paragraphs are separated by a blank line. End a line with two spaces or a \ to break it without starting a new paragraph.
• Emphasis: *em* or _em_, and **strong** or __strong__.
• Lists: -, * or + for bullets, and 1. or 1) for numbers. A list can start at any number, and lists nest when you indent them under an item's text.
• Block quotes: lines starting with >.
• Code: `inline`; blocks fenced with ``` or ~~~ and an optional language, such as ```js; or blocks indented by four spaces.
• Links: [text](https://url "title"), references such as [text][label] together with a definition [label]: https://url, and autolinks such as <https://url>.
• Images: ![alt text](picture.png).
• Thematic breaks: ---, *** or ___ on a line of their own.
• Raw HTML, backslash escapes such as \*, and entities such as ©.

And, as plugins (each can be switched off under Plugins), GitHub's extensions and more:

• Tables: rows of cells between pipes, with a row of dashes under the header. Colons in that row align a column: :--- left, :---: centred, ---: right.
• Task lists: - [ ] to do and - [x] done. Tick a box in the preview and the source is ticked too.
• Strikethrough: ~~text~~.
• Bare links: www.example.com, https://example.com and email addresses link on their own.
• Footnotes: [^1] in the text and [^1]: the note anywhere; notes are numbered and listed at the end, with links back.
• Math: LaTeX between dollars, $x^2$ inline or $$ on lines of their own around a display equation (or a ```math block).
• Diagrams: a ```mermaid block becomes a flowchart, sequence diagram, Gantt chart, pie and more, drawn by Mermaid.

Math and diagrams are drawn by libraries MarkHippo carries with it, loaded only when a document needs them, so they work offline too.

Privacy and safety

MarkHippo runs entirely in your browser. Documents are never uploaded and nothing is tracked, and pictures you paste go into the document, not to a server. The only requests the preview makes are for images that your document links to.

Markdown can contain raw HTML, and a document can come from anywhere. So scripts and event handlers in a document never run, links that would run script (javascript: and the like) are disabled, HTML that could take over the page (a redirect, a form, a different base address for links) is left out of the preview, and every link in the preview opens in a new tab so the editor is never replaced. An exported HTML page carries the same protection with it: nothing in it can run, wherever it is opened.

Under the hood: one parser, plugins

MarkHippo does not use an off-the-shelf markdown library. Its parser builds a tree of the document in which every block and inline element records exactly where it sits in the source, down to the line and column. The preview is one consumer of that tree. Syntax highlighting in the editor, autocomplete, the outline, the minimap and synced scrolling all read the same tree, so every feature agrees on what the document says. The exports start from the preview's HTML, so anything a plugin can show, it can also export.

The core of MarkHippo knows no markdown at all. It only knows how to host plugins. CommonMark itself is a plugin, written against the same interface that any other plugin uses: a plugin can add block types, inline syntax, how they are coloured in the editor, renderers for fenced code, programming languages to colour, and the suggestions in the list at the cursor. The developer overview describes the interface, and your own plugins use it too.

The Plugins button in the header lists the plugins MarkHippo is running. CommonMark is required; the others can be switched off, and MarkHippo remembers your choice. On the web, MarkHippo runs only the plugins bundled with it; the desktop app also loads your own.

Your own plugins

The desktop app loads plugins from a folder of your own, so you can add syntax, colours for a language, suggestions or palettes. A plugin is one JavaScript file, or a folder with an index.js in it.

1. Choose Plugins → Open Plugins Folder, or Open plugins folder in the Plugins list.
2. Put the plugin there.
3. Choose Plugins → Reload Plugins.

Your plugins are listed with the bundled ones, marked Yours, and can be switched off the same way. A plugin that will not load or set up is listed with the reason, and everything else carries on without it.

Plugins run inside the editor's page. They cannot reach your files or the network, and nothing runs in the documents you export. They are still code, though, so install the ones you trust. Writing a plugin walks through an example that adds ==highlighted text==.

Coming next

• A choice of where pasted pictures go in the desktop app, as well as assets.
• Export to Word (.docx).