Fix Google Books Warnings

Fix Google Books Warnings

Core Workflow

Use this skill when Google Play Books accepts an EPUB but reports warnings, or when an upload is blocked by processing issues.

1. Classify the warning:
   • CSS declaration removed
   • Metadata mismatch
   • Missing or invalid image/resource
   • Cover issue
   • EPUB parsing or validation issue
2. Locate the source:
   • Search source files first with rg.
   • If not found, inspect generated EPUB internals because Pandoc or another generator may inject CSS/HTML.
   • Check both output/*.epub and the newest dist/v*/ EPUB.
3. Fix at the source:
   • Edit Markdown, CSS, metadata, or build scripts rather than patching the final EPUB by hand.
   • For Pandoc-generated syntax highlighting CSS warnings, add --syntax-highlighting=none.
4. Rebuild:
   • Prefer the project release/package script.
   • Run EPUBCheck.
   • Rescan generated EPUB internals for the reported pattern.
5. Report:
   • Original warning category.
   • Source file or generator that caused it.
   • Exact fix.
   • Rebuilt EPUB path for upload.
   • Validation result.

Do not upload to Google Play Books or push to GitHub unless explicitly asked.

Common CSS Warning Fix

Google Play Books may warn:

Removing declaration (Bad property: -webkit-text-size-adjust)
Removing declaration (Bad property: -webkit-touch-callout)
Removing declaration (Bad property: user-select)

If these declarations are not in project CSS, they may come from Pandoc syntax highlighting inside generated XHTML. Fix by adding this to Pandoc commands:

--syntax-highlighting=none

Then rebuild and scan the EPUB internals.

Useful Checks

Read references/warning-patterns.md for reusable command patterns.

Always verify the final EPUB, not just the source files.