xml2epub

Batch convert web pages, HTML files or images to a single e-book.

Features:

• Auto-generate cover: Uses matching <title> text (per COVER_TITLE_LIST) or a random generated cover default.
• Auto-extract core content: Filters HTML to retain key elements (see SUPPORTED_TAGS).

ToC

• xml2epub
  • ToC
  • How to install
  • Basic Usage
  • API
    • Epub object
      • Epub(title)
      • Epub.add_chapter(chapter_object)
      • Epub.create_epub(output_directory)
    • create_chapter_from_file(path_to_file)
    • create_chapter_from_url(url)
    • create_chapter_from_string(html_string)
    • html_clean(input_string)
  • Tips
  • FAQ

How to install

xml2epub is available on pypi: https://pypi.org/project/xml2epub/

pip3 install xml2epub

Basic Usage

import xml2epub

## create an empty eBook, with toc located after cover
book = xml2epub.Epub("My New E-book Name", toc_location="afterFirstChapter")
## create chapters by url
#### custom your own cover image
chapter0 = xml2epub.create_chapter_from_string("https://cdn.jsdelivr.net/gh/dfface/img0@master/2022/02-10-0R7kll.png", title='cover', strict=False)
#### create chapter objects
chapter1 = xml2epub.create_chapter_from_url("https://dev.to/devteam/top-7-featured-dev-posts-from-the-past-week-h6h")
chapter2 = xml2epub.create_chapter_from_url("https://dev.to/ks1912/getting-started-with-docker-34g6")
## add chapters to your eBook
book.add_chapter(chapter0)
book.add_chapter(chapter1)
book.add_chapter(chapter2)
## generate epub file
book.create_epub("Your Output Directory")

After a short wait (no errors), "My New E-book Name.epub" will be generated in "Your Output Directory":

For more examples, check the examples directory.

If no cover is inferred from the HTML, a random cover is generated.

API

Epub object

Epub(title)

Epub(title, creator='dfface', language='en', rights='', publisher='dfface/xml2epub', epub_dir=None, toc_location='end')

Creates Epub object (adds book info/chapters, generates EPUB file).

• title (str): EPUB title (per spec).
• creator (Optional[str]): EPUB author (per spec).
• owner (Optional[str]): The owner of this file—yes, that's you! This affects the text in the top banner if you use our generated cover.
• language (Optional[str]): EPUB language (per spec).
• rights (Optional[str]): EPUB copyright (per spec).
• publisher (Optional[str]): EPUB publisher (per spec).
• epub_dir (Optional[str]): Intermediate file path (default: system temp path).
• toc_location (Optional[str]): ToC position (default: end; options: beginning/afterFirstChapter/end):
  • beginning: ToC → chapters
  • afterFirstChapter: Chapter1 (cover) → ToC → chapters
  • end: Chapters → ToC

Epub.add_chapter(chapter_object)

Add Chapter object (Created via 3 chapter creation methods) to EPUB.

Epub.create_epub(output_directory)

Epub.create_epub(output_directory, epub_name=None, absolute_location=None)

Generate EPUB file.

• output_directory (str): Output directory for EPUB.
• epub_name (Optional[str]): EPUB filename (no .epub suffix; printable chars only, defaults to title).
• absolute_location (Optional[str]): Absolute path/name (no .epub suffix; overrides default ${cwd}/${output_directory}/${epub_name}.epub; requires write permissions).

create_chapter_from_file(path_to_file)

create_chapter_from_file(file_name, url=None, title=None, strict=True, local=False)

Create Chapter from HTML/XHTML file.

• file_name (string): HTML/XHTML file path.
• url (Optional[string]): Infers title; recommended for relative links.
• title (Optional[string]): Chapter name (uses HTML <title> if None).
• strict (Optional[boolean]): Strict cleaning (removes inline styles, trivial attrs); default True.
• local (Optional[boolean]): Use local resources (copy images/CSS via paths, no online fetch).

create_chapter_from_url(url)

create_chapter_from_url(url, title=None, strict=True, local=False)

Create Chapter by extracting webpage from URL.

• url (string): Website link (recommended for resolving relative links).
• title (Optional[string]): Chapter name (uses HTML <title> if None).
• strict (Optional[boolean]): Strict page cleaning (removes inline styles/attrs; default True).False allows image links for custom covers.
• local (Optional[boolean]): Use local resources (copy images/CSS via paths, no online fetch).

create_chapter_from_string(html_string)

create_chapter_from_string(html_string, url=None, title=None, strict=True, local=False)

Create Chapter from string (base method for URL/file variants).

• html_string (string): HTML/XHTML string; or image URL (strict=False) / image path (strict=False + local=True). Image as cover if title is None/ in [COVER_TITLE_LIST] (e.g., cover).
• url (Optional[string]): Infers title; recommended for relative links.
• title (Optional[string]): Chapter name (uses HTML