Markdown to HTML on the Mac

Checked November 2026 against the pandoc manual, cmark's manual page, Homebrew, GitHub's REST docs, Typora's export docs and the VS Code docs. Coffee isn't affiliated with any of them.

For most jobs, use pandoc: pandoc note.md -f gfm -s --embed-resources -o note.html gives you one self-contained page. The Mac's built-in textutil command lists HTML, RTF, Word and others but not Markdown, so you need another tool. Below are pandoc and three lighter routes, followed by what Coffee's own export does and where it stops.

Pandoc

Pandoc is a free converter that installs with Homebrew, or from an installer on its site:

brew install pandoc

By default, its manual says, pandoc produces a fragment, which is what you want for pasting into a site or template:

pandoc note.md -f gfm -o note.html

The -f gfm tells it to read GitHub Flavored Markdown. Without it, pandoc reads its own richer Markdown, which is the better choice if you use its extras. For a complete page, add -s:

pandoc note.md -f gfm -s --metadata title="March notes" -o note.html

A few more options cover most needs:

• --embed-resources puts images and other files inside the HTML as data: addresses, so you can send a single file. Use it with -s.
• --css=style.css links your own stylesheet.
• --metadata title="..." sets the page title. A title in front matter does the same job.

Footnotes and task lists are on by default in pandoc's gfm format, so this is also the way to get real footnotes from a note whose editor doesn't draw them.

cmark

cmark is the reference implementation of CommonMark, written in C. It does one job, and reads from a file or standard input and writes to standard output:

brew install cmark
cmark note.md > note.html

You get the converted content and no page around it. As it follows CommonMark, tables and task lists aren't covered. Homebrew also has cmark-gfm, GitHub's implementation of GFM, for those.

GitHub's API

If you want HTML close to what GitHub produces, its REST API has an endpoint for it. Here's the docs' example with GFM mode added:

curl -L -X POST https://api.github.com/markdown \
  -H "Accept: text/html" \
  -d '{"text": "Hello **world**", "mode": "gfm"}'

There's also /markdown/raw for sending plain text. Your text goes to GitHub, so keep private notes away from this.

An editor's export

Many Markdown editors have an export command, which is the easiest route for an occasional file. Typora, for example, exports styled HTML and a version without styles, for when you bring your own. The VS Code docs describe a preview that's there from the start, but don't describe an HTML export, and point to extensions for more.

Which to use

Coffee's HTML export

Press ⌘E and choose HTML at the bottom of the panel. You get one file for the current note, with a built-in stylesheet and the note's title as the page title.

What it carries over:

• Headings, bold, italic, strikethrough, highlights, inline code, code blocks, quotes, callouts, dividers, links, tables with their alignment colons, and checklists.
• Footnotes, numbered and linked both ways, with the notes listed at the end.
• $$ maths blocks as drawn formulas, and Mermaid flowcharts, pie charts and sequence diagrams as a picture after their code. Other Mermaid kinds stay as code.
• Local PNG, JPEG, GIF and WebP images on a relative path, placed inside the file as data: addresses. So it still works once you move or send it. Images on other paths, or in other formats, stay as ordinary addresses. Web images stay as links to the web.
• Calculation answers, as the note shows them. None if calculations are off.

What it leaves out or changes:

• Front matter is removed.
• [[Note links]] become plain text, as the page has no other note to point to.
• Coffee's comments aren't included, as they aren't in the file.
• HTML comments such as <!-- draft --> are left out, unless they're inside code. They stay in your note.
• A javascript:, data: or vbscript: address that you typed is replaced with #.

Where it's simpler than pandoc

Coffee's exporter is built on the editor's line-by-line parser, which keeps it small and consistent with what you see. It also means the output is simpler than a full Markdown converter's, and you should know the differences before you publish with it:

• Lists stay tight. Nesting and a list's starting number come through, and a blank line between items doesn't start a new list, but the items don't get the extra <p> a full converter gives a list with blank lines in it.
• Raw HTML appears as text, apart from <mark> and comments.
• Reference links, underlined headings and indented code stay as written, as they do in the editor.
• There's little to hook into. Headings have no id, code blocks have no language class, and there's no setting for the stylesheet. You can edit the file afterwards, of course.

Wrapped lines join into one paragraph, as in any Markdown converter, so a note where each line stands by itself reads as running text unless you end those lines with two spaces or a \. A line with a calculation's answer on it stays a line of its own.

For a single page of ordinary notes, none of this may matter, and it's quick. For a long document, or anything going into a template, pandoc will do a better job from the same .md file. Coffee's notes are plain files, so you can use both.

One more thing: exporting a private note creates an ordinary readable file. The lock stays on the note, not on what you take out of it.

For a page meant for printing, the PDF guide is the better read.

Questions

How do I convert Markdown to HTML on a Mac without installing anything?

The built-in textutil command doesn't list Markdown. If curl to GitHub's API suits you and the text isn't private, that needs no install. Otherwise, you need a tool like pandoc or an editor with an HTML export.

What's the difference between a fragment and a standalone HTML file?

A fragment is only the converted content, ready to drop into a template. A standalone file has the surrounding page, including a title. Pandoc gives a fragment by default, and -s makes it standalone.

Does Coffee's HTML export include images?

Local PNG, JPEG, GIF and WebP images on a path relative to the note are placed inside the file. Web images stay as links, so they load from their site when the page is opened.

Does Coffee's HTML export keep nested lists?

Yes, including a list of one kind inside another. A numbered list also keeps the number it starts at.