Publish Ebook Preview

Publish Ebook Preview

Overview

Use this skill to prepare an ebook project for EPUB upload and web preview publishing. Favor simple, reproducible build steps, clean EPUB packaging, and a restrained preview site that shows only the first half of the book while linking readers to Google Books for purchase.

Workflow

1. Inspect the repository structure before editing.

   • Look for src/ Markdown chapters, web/ static site files, epub/ EPUB source tree, and tools/build_epub.py or equivalent scripts.
   • Read project instructions such as AGENTS.md, BOOK_STRUCTURE.md, and validation scripts.
   • Check git status --short and preserve unrelated user changes.

2. Rebuild the EPUB deterministically.

   • Prefer an existing build script, usually python tools/build_epub.py.
   • Keep the first ZIP entry as mimetype, uncompressed, with content exactly application/epub+zip.
   • Keep the EPUB package minimal: top-level entries should normally be only mimetype, META-INF/, and OEBPS/.
   • Include every OEBPS/ resource in content.opf manifest.
   • Prefer PNG/JPG cover images for Google Books compatibility. Avoid relying on SVG-only covers.
   • Ensure cover.xhtml, content.opf, nav.xhtml, and toc.ncx all point to the same cover resource.
   • Use a stable dc:identifier when regenerating a revised version of the same book.

3. Build the web preview with the first half of chapters.

   • If the book has 10 chapters, expose chapters 1-5 as the preview.
   • If chapter count differs, use the first ceil(total / 2) chapters unless the user gives a specific preview range.
   • Keep later chapters visible only as locked/listed items or omit their content, depending on the existing site pattern.
   • Do not duplicate full paid-book content into the free preview site.

4. Add the Google Books purchase link at the end of chapter pages.

   • Put the CTA after the visible chapter content, effectively on the last page/last section of each web chapter view.
   • Use the project's existing CTA style and wording when present.
   • The link should point directly to the Google Books purchase/detail URL supplied by the user or already used in the project.
   • If no URL is available, leave a clear placeholder constant in the code and tell the user it needs the final Google Books URL.

5. Validate before finishing.

   • Run the project validator if present, for example python tools/validate_project.py.
   • Parse XML/XHTML files in the EPUB when possible: .xml, .opf, .ncx, .xhtml.
   • Confirm ZIP contents do not include source-only files such as root-level cover source images.
   • Confirm the web preview limit is implemented in code or data.
   • If epubcheck is installed, run it on the final .epub. If it is unavailable, state that clearly.

EPUB Build Notes

When writing or editing a build script:

with ZipFile(output_path, "w") as epub_zip:
    epub_zip.write(epub_dir / "mimetype", "mimetype", compress_type=ZIP_STORED)
    for file_path in sorted(epub_dir.rglob("*")):
        if file_path.is_dir() or file_path.name in {output_path.name, "mimetype"}:
            continue
        epub_zip.write(file_path, file_path.relative_to(epub_dir).as_posix(), compress_type=ZIP_DEFLATED)

Add explicit exclusions for source-only assets, for example an original cover1.png copied into OEBPS/Images/cover.png.

For Google Books review, prefer:

• OEBPS/Images/cover.png
• OPF manifest item: media-type="image/png" properties="cover-image"
• meta name="cover" content="cover-image"
• cover.xhtml with <img src="../Images/cover.png" .../>

Web Preview Pattern

For JavaScript-driven static sites, look for code like:

const previewChapters = chapters.slice(0, 5);

Adjust 5 to the first half of the chapter count. If possible, compute it:

const previewCount = Math.ceil(chapters.length / 2);
const previewChapters = chapters.slice(0, previewCount);

Place the Google Books CTA after rendered chapter content, not before the reader reaches the chapter ending.

Final Response

Report:

• The final EPUB path and whether the filename was reused.
• The preview range, such as chapters 1-5 of 10.
• The Google Books link location in the web chapter flow.
• Validation commands run and whether epubcheck was available.