How does Markdown convert to a valid EPUB 3.3 book?
Inside a browser Web Worker, the converter parses your Markdown manuscript and YAML frontmatter, splits chapters by heading level, compiles KaTeX equations into MathML, and writes a complete OCF ZIP container. Your unpublished manuscript bytes stay entirely on your device throughout packaging.
Writing an uncompressed mimetype ZIP inside the browser
A valid EPUB archive is a specifically ordered ZIP container defined by the W3C EPUB 3.3 Recommendation. Many generic ZIP tools compress every file by default, which triggers instant rejection in reading systems.
Our packager calls fflate.zipSync with explicit entry ordering so the 20 bytes of mimetype (application/epub+zip) sit first at compression level 0 (STORE) with 0 bytes of extra header metadata under ISO 23736 OCF packaging rules. Remaining files inside META-INF and OEBPS use level 6 deflate compression.
- Container pointer: Writes
META-INF/container.xmlpointing toOEBPS/content.opfas the root package file. - Zero-upload packaging: Compiles fonts, stylesheets, images, and XML documents in local worker memory without touching external servers.
Building the OPF spine, navigation document, and NCX
Every exported book ships with OEBPS/content.opf (version="3.0") carrying dcterms:modified timestamps, language declarations, and ordered spine references. A pre-pass maps heading slugs across split files so #heading-id links pointing to other chapters resolve cleanly.
To maintain compatibility across modern reading apps and older dedicated hardware, the generator creates both EPUB 3.3 OEBPS/nav.xhtml (epub:type="toc" plus cover, TOC, and body-matter landmarks) and legacy EPUB 2 OEBPS/toc.ncx (dtb:depth="2"). After clicking Generate EPUB, select Validate in EPUB checker to pass the archive straight to the EPUB checker.
YAML frontmatter keys, chapter splits, and typography themes
The Markdown to EPUB parser supports standard YAML metadata blocks alongside syntax from the GitHub Flavored Markdown Specification, including pipe tables, fenced code blocks, task checkboxes, blockquotes, and strikethrough text. Fields typed inside Book settings (override YAML) always take precedence over file headers during export.
| Setting or YAML key | Control or source | EPUB output behavior | Accepted options or defaults |
|---|---|---|---|
| Book title | title or H1 heading |
Sets dc:title and output filename slug |
Falls back to first H1 or Untitled Book |
| Author & Language | author / language |
Populates dc:creator and BCP-47 dc:language |
Default language en |
| Publisher & ISBN / UUID | publisher / identifier |
Writes dc:publisher and dc:identifier |
Generates deterministic urn:uuid if blank |
| Chapter split | Level dropdown | Splits XHTML documents at heading boundaries | Split on # H1, Split on # H1 & ## H2, or Single chapter |
| Theme | Typography dropdown | Generates OEBPS/styles.css body fonts |
Book serif, Modern sans, or Classic Georgia |
| TOC spine & EAA | Sidebar checkboxes | Adds nav to reading spine and writes schema:* |
Both enabled by default |
Generated stylesheets default to a readable 16 px font size (1.55 line height), orphans: 2, widows: 2, and JetBrains Mono styling for inline and fenced code blocks. If copyeditors still need track-changes review before freezing ebook chapters, send the same source file through our editable DOCX manuscript exporter.
Rendering KaTeX MathML, cover art, and cross-chapter links
Technical writers and educators often convert Markdown with YAML frontmatter into EPUB 3.3 books containing formulas, diagrams, and illustrated figures. This workflow avoids brittle screenshots by compiling clean XML math alongside self-contained image assets.
Compiling native MathML equations without raster images
Inline and display TeX equations pass through KaTeX configured for pure mathml output under the W3C MathML Version 3.0 Specification. An XML entity sanitizer converts HTML named entities into numeric character references so strict XHTML parsers never fail on malformed entity declarations.
Chapters containing formulas receive properties="mathml" inside OEBPS/content.opf, and the result list marks each affected file with a MathML badge. Readers that reflow text dynamically resize equations alongside surrounding paragraphs rather than clipping pixelated PNG blocks.
Handling cover artwork, alt text, and embedded data URIs
Select Add cover image to attach JPG, PNG, WebP, or GIF artwork, then describe visual details inside Cover image alt text. Embedded base64 data:image/* URIs inside your Markdown body are extracted into OEBPS/images/ and registered in the OPF manifest automatically.
Tip: Inline base64 data URIs or local uploads keep every illustration self-contained inside the OCF archive. If your manuscript references external web images over HTTPS, replace those links before exporting offline reader editions so flights and disconnected e-readers display every figure cleanly.
When a mathematical report uses fixed multi-column PDF typography, keep the print layout instead of rebuilding columns by hand. You can crop fixed-layout PDFs for Kindle screens so diagrams and tables stay readable.
Adding EAA accessibility metadata and choosing reflowable EPUB
Digital publishing mandates increasingly require structured semantic disclosures inside ebook packages alongside clean typography. Generating compliant metadata directly from Markdown saves post-production editing inside desktop packaging suites and reduces late compliance errors before bookstore submission.
Declaring EPUB Accessibility 1.1 and schema properties
Leaving Embed EAA accessibility schema metadata checked inserts package-level declarations matching the W3C EPUB Accessibility 1.1 specification. Content OPF metadata declares schema:accessMode (textual, adding visual when images are present), schema:accessModeSufficient, schema:accessibilityHazard set to none, and an explanatory schema:accessibilitySummary.
- Core features declared: Writes
structuralNavigation,tableOfContents, andreadingOrderautomatically for every exported archive so assistive reading apps recognize chapter landmarks. - Conditional features declared: Appends
MathMLwhen equations appear andalternativeTextwhen cover or inline image descriptions exist inside the manuscript.
When reflowable EPUB outperforms fixed-layout pages
Reflowable EPUB 3.3 books adapt across phone viewports, 6-inch e-ink displays, and desktop reading apps because users control font scaling and margins. By contrast, textbooks locked to rigid grids or workshop presentations benefit from separate page-based exports.
When lecture notes originally written for an ebook need live visual projection in a classroom, you can prepare slide decks offline from Markdown notes using the exact same heading hierarchy. Keeping plain Markdown as your canonical draft lets every export target stay synchronized locally.