--- title: "Markdown to HTML on the Mac" author: Pedro Thomaz source: https://coffeetext.app/blog/markdown-to-html-mac --- # Markdown to HTML on the Mac > Checked November 2026 against the [pandoc manual](https://pandoc.org/MANUAL.html), [cmark's manual page](https://raw.githubusercontent.com/commonmark/cmark/master/man/man1/cmark.1), [Homebrew](https://formulae.brew.sh/formula/cmark), [GitHub's REST docs](https://docs.github.com/en/rest/markdown/markdown), [Typora's export docs](https://support.typora.io/Export/) and the [VS Code docs](https://code.visualstudio.com/docs/languages/markdown). 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](https://pandoc.org/installing.html) is a free converter that installs with Homebrew, or from an installer on its site: ``` brew install pandoc ``` By default, [its manual](https://pandoc.org/MANUAL.html) 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](https://coffeetext.app/blog/what-is-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](https://coffeetext.app/blog/extended-markdown-footnotes-task-lists) from a note whose editor doesn't draw them. ## cmark [cmark](https://github.com/commonmark/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](https://formulae.brew.sh/formula/cmark-gfm), GitHub's implementation of GFM, for those. ## GitHub's API If you want HTML close to what GitHub produces, [its REST API](https://docs.github.com/en/rest/markdown/markdown) 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](https://support.typora.io/Export/), for example, exports styled HTML and a version without styles, for when you bring your own. The [VS Code docs](https://code.visualstudio.com/docs/languages/markdown) 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 | You want | Use | |---|---| | One self-contained page, with control | Pandoc with `-s --embed-resources` | | A fragment for a template or script | Pandoc or cmark | | Output that matches GitHub | GitHub's API or cmark-gfm | | One note as a page, without Terminal | An editor's export | ## 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](https://coffeetext.app/blog/calculator-in-notes-mac), 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 `` 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 `

` a full converter gives a list with blank lines in it. - **Raw HTML appears as text**, apart from `` 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](https://coffeetext.app/blog/password-protect-notes-mac) 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](https://coffeetext.app/blog/markdown-to-pdf-mac) 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. --- Written by Pedro Thomaz, who makes Coffee, a Markdown editor for the Mac on macOS 15 or later. It's free for 14 days with no card or account, then €3 a month, €29 a year, or €79 once with two years of updates. More at https://coffeetext.app/llms-full.txt