ShareGPT

On Linux, the most reliable and widely used approach is to use Pandoc. It natively understands Markdown, EPUB structure, and chapter boundaries.

Below is a production-grade workflow.

---

Recommended Tooling

• pandoc (core conversion engine)

• Optional:

  • GNU Make (automation)
  • CSS (styling)
  • YAML metadata file (EPUB metadata)

Install Pandoc:

sudo apt install pandoc
# or
sudo dnf install pandoc
# or
sudo pacman -S pandoc

---

Basic Concept (How Chapters Work)

Pandoc treats each input Markdown file as a separate section. When generating EPUB:

• Each file becomes a chapter.
• Top-level headings (# Heading) become chapter titles.
• File order determines chapter order.

---

Minimal Example

Assume this structure:

book/
├── chapter01.md
├── chapter02.md
├── chapter03.md

Create the EPUB:

pandoc chapter01.md chapter02.md chapter03.md \
  -o book.epub

That is sufficient for a valid EPUB with three chapters.

---

Best-Practice Structure (Recommended)

1. Use Proper Headings

Each chapter file should start with a level-1 heading:

# Chapter 1: Introduction

Your content here…

Pandoc uses this for the EPUB table of contents.

---

2. Add Metadata (Title, Author, Language)

Create metadata.yaml:

title: "My Book Title"
creator:
  - role: author
    text: "Author Name"
language: en
identifier: urn:uuid:12345678-1234-5678-1234-567812345678

Then run:

pandoc metadata.yaml chapter01.md chapter02.md chapter03.md \
  -o book.epub

---

Styling the EPUB (CSS)

Create epub.css:

body {
  font-family: serif;
  line-height: 1.5;
}

h1 {
  page-break-before: always;
}

Generate EPUB with styling:

pandoc metadata.yaml chapter01.md chapter02.md chapter03.md \
  --css=epub.css \
  -o book.epub

---

Automatic Chapter Ordering

If you have many files:

pandoc metadata.yaml $(ls chapters/*.md | sort) \
  -o book.epub

Or explicitly:

pandoc metadata.yaml chapters/01-*.md chapters/02-*.md \
  -o book.epub

---

Advanced Options (Commonly Used)

Table of Contents Depth

--toc --toc-depth=2

Cover Image

--epub-cover-image=cover.jpg

Split Chapters by Heading (Single File Input)

If you later combine files:

--split-level=1

---

Validating the EPUB (Optional but Recommended)

Install epubcheck:

sudo apt install epubcheck

Validate:

epubcheck book.epub

---

Summary

Shortest correct answer:

pandoc *.md -o book.epub

Best practice:

• One Markdown file per chapter
• Each file starts with # Chapter Title
• Use a YAML metadata file
• Add CSS for layout consistency