--- title: "Turning Markdown into an EPUB e-book on the Mac" author: Pedro Thomaz source: https://coffeetext.app/blog/markdown-to-epub-mac --- # Turning Markdown into an EPUB e-book on the Mac > Checked November 2026 against [pandoc's EPUB guide](https://pandoc.org/epub.html), the [pandoc manual](https://pandoc.org/MANUAL.html), [Apple's Books guide](https://support.apple.com/en-au/guide/books/ibkseed72068/5.0/mac) and [EPUBCheck](https://www.w3.org/publishing/epubcheck/). Coffee isn't affiliated with any of them. An EPUB is a zipped bundle of web pages with a table of contents, which is why Markdown converts to it so well. The free route is pandoc, one command in Terminal: list your chapter files in order and name the output `.epub`. Then open the result in Apple Books to read it as a reader would. If you'd rather not use Terminal, some Markdown editors export EPUB directly, Coffee among them. ## Before you start Whatever tool you use, a little structure in the Markdown makes a better book: - **One file per chapter** is easiest to manage, though one long file works too. - **Start each chapter with a level-one heading**, a single `#`. Tools use these to split chapters and build the table of contents. - **Keep images next to the files**, with relative paths, so the converter can find and include them. - **Avoid page-based thinking.** An e-book reflows to fit the screen, so there are no page numbers and no fixed line breaks. ## With pandoc [Pandoc](https://pandoc.org/epub.html) is free and runs on the Mac. Its [installation page](https://pandoc.org/installing.html) offers a package installer, or `brew install pandoc` if you use Homebrew. The basic command lists the chapters in reading order: ``` pandoc -o book.epub chapter1.md chapter2.md chapter3.md ``` Pandoc guesses from the `.epub` ending what to make, and by default produces EPUB 3. Its manual says it splits the book into chapters at level-one headings, and `--split-level` changes that. ### Title, author and language Without metadata, the book has no proper title. The simplest fix, from pandoc's EPUB guide, is a small file of its own, say `title.txt`, listed first: ``` --- title: Notes from the Coast author: Ana Silva lang: en-GB --- ``` Then: ``` pandoc -o book.epub title.txt chapter1.md chapter2.md chapter3.md ``` The [manual's EPUB metadata section](https://pandoc.org/MANUAL.html) lists more fields, including `rights`, `date`, `publisher` and `identifier`, for when you're publishing properly. ### A cover Add a cover image with `--epub-cover-image`: ``` pandoc -o book.epub --epub-cover-image=cover.jpg title.txt chapter1.md chapter2.md ``` The manual recommends keeping the image under 1000 pixels in width and height. You can also set `cover-image: cover.jpg` in the metadata block instead. ### Styling Pandoc's default style is deliberately plain. `--css=book.css` uses your own stylesheet. Keep it modest, because e-book readers let people change fonts and sizes, and many override what you set. Pandoc also handles maths well. Its EPUB 3 output turns TeX maths into MathML, which [writing maths in Markdown](https://coffeetext.app/blog/math-equations-in-markdown) covers in more detail. ## Checking the book Open the EPUB in Apple Books. [Apple's guide](https://support.apple.com/en-au/guide/books/ibkseed72068/5.0/mac) says to choose File, then Import, select the file and click Import, or drag it into your library. Then look for the things that usually go wrong: - **The table of contents.** Every chapter should be there, in order, with the right title. - **Images.** Each should appear, at a sensible size. - **Chapter starts.** Each chapter should begin on a fresh screen. - **Odd characters.** Leftover Markdown, such as a stray `**`, means something wasn't converted. - **Light and dark.** Switch the reader's theme, and check that text and images still read well. If you plan to sell the book or send it to a store, run it through [EPUBCheck](https://www.w3.org/publishing/epubcheck/) too. It's the free, open-source conformance checker for EPUB, a W3C project maintained by the DAISY Consortium, and it runs from Terminal as `epubcheck book.epub`. Apple Books opening a file doesn't mean the file is valid. ## In Coffee Coffee has two ways to make an EPUB, with no Terminal. **One note.** Export the note as EPUB, alongside the PDF, Word, HTML, Markdown and plain text options. You get an EPUB 3 file with a table of contents built from the note's headings. Headings, lists, tables, images, footnotes and callouts come through, `$$` maths blocks are drawn as formulas, and Mermaid flowcharts, pie charts and sequence diagrams are drawn as diagrams. **A whole book.** Export, then Book, makes one EPUB from the notes in the open note's folder, or from a tag in the sidebar. Each note becomes a chapter, and chapters are ordered by note title, so numbering them, as in "01 Arrival", "02 The Harbour", keeps them in the order you mean. Private notes are left out. Some limits, so you can decide whether it's enough: - **No cover image and no custom stylesheet.** The look is Coffee's own. - **Order comes from titles.** There's no separate list to drag chapters around in. - **Coffee doesn't use pandoc**, and has no LaTeX export. If you need pandoc's control over metadata and styling, use pandoc on the same files, since they're plain Markdown. Either way, check the result in Apple Books before you send it anywhere. For printable copies of the same notes, see [Markdown to PDF on the Mac](https://coffeetext.app/blog/markdown-to-pdf-mac). ## Questions ### How do I convert Markdown to EPUB on a Mac? Install pandoc and run `pandoc -o book.epub chapter1.md chapter2.md`, listing chapters in order. Some Markdown editors, including Coffee, export EPUB without Terminal. ### How do I add a cover to an EPUB made with pandoc? Use `--epub-cover-image=cover.jpg` in the command, or set `cover-image` in the metadata block. Pandoc's manual recommends an image under 1000 pixels wide and high. ### How do I open an EPUB on a Mac? In Apple Books, choose File, then Import, and select the file, or drag it into the library. ### Can Coffee make one EPUB from several notes? Yes. Export, then Book, turns the notes in a folder, or under a sidebar tag, into one EPUB with a chapter per note, ordered by title. Private notes are left out. --- 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