Markdown EPUB-ra Tartalomjegyzékkel, Fejezetekkel és Borítóval egy API-hívásban

The publishing industry spent decades building elaborate toolchains for book production. Manuscripts moved from word processors through page layout software to PDF generators to print-ready files through a pipeline that involved multiple specialists and multiple software licenses at each stage. When e-books arrived, the pipeline gained additional complexity rather than simplifying: the same manuscript now needed to produce both print-ready PDFs and reflowable EPUBs, formats with fundamentally different philosophies about how content should be presented. The print format locks everything in place. The e-book format lets everything flow. Producing both from a single source is a problem that the traditional publishing toolchain handles with all the elegance of a patchwork quilt.

Writers who self-publish face this toolchain complexity without the institutional support that traditional publishers provide. The manuscript exists as a Word document or a Google Doc. Converting it to a properly formatted EPUB requires either learning specialized e-book production software (Calibre, Sigil, Vellum) or paying a formatter who charges per project. The formatting step, which adds no creative value to the book, becomes a bottleneck between finishing the manuscript and making it available to readers. For authors publishing multiple books, the cumulative cost and time of this formatting step is significant and entirely predictable, making it an ideal candidate for automation.

The Ebooks API reduces the entire conversion process to a single API call. Write the book in Markdown, which is a format that any text editor can produce and any writer can learn in ten minutes. Send the Markdown content along with metadata and an optional cover image. Receive a professional EPUB file with a structured table of contents, properly delineated chapters, embedded cover image, and all the metadata that e-book retailers and libraries require. One input, one call, one output. The entire publishing toolchain compressed into an HTTP request.

Why Markdown Is the Ideal Authoring Format for Books

Markdown's suitability for book writing is not immediately obvious to writers accustomed to rich text editors. The format looks plain, almost primitive, compared to the formatted view in Word or Google Docs. But this apparent simplicity is precisely its strength for long-form writing. Markdown separates content from presentation entirely, which means the writer focuses on what they are saying without being distracted or constrained by how it will look. The presentation decisions happen later, during the conversion process, where they can be applied consistently and changed wholesale without touching the manuscript.

Chapter headings in Markdown are marked with hash symbols. A single hash indicates the book title. Double hashes indicate chapter titles. Triple hashes indicate section headings within chapters. This hierarchical structure maps directly to the EPUB's navigation structure: chapter titles become entries in the table of contents, section headings become sub-entries, and the book title becomes the top-level navigation element. The writer creates the book's structure through the simple act of marking headings, and the API translates that structure into the EPUB's navigational framework automatically.

Paragraphs are separated by blank lines. Emphasis is marked with asterisks. Block quotes are marked with angle brackets. Links are marked with brackets and parentheses. Each of these Markdown conventions has a direct equivalent in the EPUB's internal HTML, and the conversion is deterministic: the same Markdown input always produces the same EPUB structure. This predictability is important for authors who publish revisions or updated editions, because changes to the Markdown produce correspondingly precise changes in the EPUB without introducing formatting side effects.

The portability of Markdown files is another significant advantage. A manuscript written in Markdown is a plain text file that can be opened, edited, and version-controlled with any tool on any operating system. It is not locked to a specific word processor version, does not require a specific software license to access, and does not degrade over time as software formats evolve. A Markdown manuscript written today will be readable in exactly the same form in ten or twenty years, which is more than can be said for any proprietary document format. For authors who plan to maintain and update their works over long periods, this format longevity is a meaningful benefit.

Metadata and What Makes an EPUB Professional

A professional EPUB file contains more than just the book's content. It contains metadata that describes the book to the systems that distribute, catalog, and display it. Title, author, publisher, language, publication date, ISBN, description, and subject categories are all embedded in the EPUB file as structured metadata that e-book retailers, library systems, and reading applications use to properly catalog and display the book.

The API accepts this metadata alongside the Markdown content and embeds it in the EPUB according to the OPF (Open Packaging Format) specification that defines how EPUB metadata should be structured. The metadata is not just pasted into a file header; it is formatted according to the Dublin Core metadata standards that EPUB uses, with proper element types, attributes, and namespace declarations that validation tools and retail platforms expect. An EPUB with properly structured metadata is accepted by Amazon KDP, Apple Books, Kobo, Google Play Books, and every other major retail platform without modification.

The cover image is a particularly important metadata element because it is the first thing a potential reader sees in any retail environment. The API accepts a cover image file (JPEG or PNG) and embeds it in the EPUB with the proper manifest entries, spine references, and metadata declarations that cause reading applications to display it as the book's cover. The image is also resized and optimized if needed to meet the dimension and file size requirements that retail platforms impose, ensuring the EPUB is retail-ready without manual image processing.

ISBN embedding deserves specific mention because it is the identifier that connects the book to the global book trade infrastructure. An EPUB with a properly embedded ISBN can be cataloged by libraries, tracked by retailers, referenced by review sites, and identified unambiguously in any context where books are discussed or sold. The API embeds the ISBN in the EPUB's metadata using the format specified by the International ISBN Agency, ensuring compatibility with the systems that use ISBNs for identification and catalog management.

The Table of Contents and Chapter Structure

The table of contents in an EPUB serves two functions that are distinct from the table of contents in a printed book. In a printed book, the TOC is a page that lists chapter titles and page numbers. In an EPUB, the TOC is a navigational element that enables direct jumping to any chapter or section, and it is displayed by the reading application's navigation interface rather than as a rendered page. A well-structured EPUB TOC makes the book navigable in the same way that a well-structured website is navigable: readers can jump directly to any chapter without scrolling through the entire book sequentially.

The API generates the TOC from the heading structure in the Markdown content. Each level-two heading (double hash) becomes a chapter entry in the TOC. Each level-three heading (triple hash) becomes a sub-entry under its parent chapter. This two-level navigation structure provides enough granularity for most books without overwhelming the navigation interface with excessive sub-entries. The TOC is generated as both a navigational element (NCX for EPUB2 compatibility and Navigation Document for EPUB3) ensuring the book works correctly in older e-readers as well as modern reading applications.

Chapter breaks in the generated EPUB correspond to the level-two headings in the Markdown. Each chapter begins on a new page in the e-reader, which provides the visual separation between chapters that readers expect. The API inserts the appropriate XHTML page breaks and spine entries to ensure that e-readers treat each chapter as a distinct navigational unit rather than a continuous scroll. This chapter separation also enables e-readers to display chapter titles in the reading progress indicator, showing the reader which chapter they are currently in and how far through it they have progressed.

For books with complex structures, such as parts containing multiple chapters, appendices, or front matter sections, the Markdown heading hierarchy accommodates these structures naturally. Level-one headings can denote parts, level-two headings denote chapters within parts, and level-three headings denote sections within chapters. The API maps this hierarchy to the EPUB's navigation structure faithfully, producing a TOC that reflects the book's organizational logic regardless of how many levels of nesting the author uses.

One Call and What the API Request Looks Like

The API call that produces the EPUB is a POST request containing the Markdown content, metadata fields, and optionally a cover image file. The Markdown content is the body of the book, marked up with headings, paragraphs, and any other Markdown elements the author uses. The metadata fields are key-value pairs: title, author, language, description, ISBN, publication date, and any additional Dublin Core fields that the author wants to include. The cover image, if provided, is uploaded as a file attachment.

The response is the EPUB file itself, ready to download, distribute, or upload to a retail platform. The file conforms to the EPUB 3 specification with EPUB 2 compatibility fallbacks, which ensures it works on every modern e-reader and reading application as well as older devices that support only the earlier standard. The file passes EPUB validation (epubcheck) without errors, which is a requirement for submission to most retail platforms and a strong indicator of structural correctness.

For authors with multiple books or multiple editions, the API call can be integrated into an automated publishing pipeline. The Markdown manuscript is stored in version control (Git, for example), the metadata is stored in a configuration file, and a build script sends both to the API whenever a new version needs to be generated. This automated pipeline means that corrections, updates, and new editions can be produced and distributed in minutes rather than the hours or days that manual formatting workflows require. A typo fix takes thirty seconds: edit the Markdown, run the build script, upload the new EPUB to the retail platform.

The simplicity of the API call belies the complexity of the operations happening behind it. The API parses the Markdown, generates XHTML content files for each chapter, creates the OPF manifest and spine, generates the NCX and Navigation Document, embeds and references the cover image, structures all metadata according to Dublin Core and EPUB specifications, packages everything into the EPUB container format (which is actually a specially structured ZIP file), and validates the result against the EPUB specification. All of these operations, each of which represents a potential point of failure in manual EPUB production, are handled automatically and reliably every time.