DOCSEARCHbyAlgolia
Submit Docs

EPUBCheck Documentation

repository·main·Indexed 23 days ago

https://github.com/w3c/epubcheck

The official W3C conformance checker for EPUB publications, used to validate EPUB 2 and EPUB 3 files against their respective specifications. EPUBCheck is available as a standalone command-line tool, a Docker image, or a Java library via the com.adobe.epubcheck.api package. It provides detailed validation reports including severity levels (FATAL, ERROR, WARNING, INFO, USAGE, SUPPRESSED) and metadata schemas for CheckerMetadata and PublicationMetadata.

Tokens
1.7K
Snippets
5
Records
13
Agent score
82%

What's inside EPUBCheck

  1. Overview of EPUBCheck

    main

    EPUBCheck is the official conformance checker for EPUB publications. It can be used in two ways:

    1. As a standalone command-line tool.
    2. As a Java library for integration into other applications.

    It is used to validate both EPUB 2 and EPUB 3 files. EPUB 3 publications are checked against the EPUB 3.3 specification.

  3. Run EPUBCheck as a command-line tool

    main

    To run EPUBCheck as a standalone tool, you must have a Java runtime (version 1.7 or higher) installed. You can execute the tool against an EPUB file using the java -jar command. By default, all detected errors are printed to the standard error stream.

    java -jar epubcheck.jar file.epub

  5. Run EPUBCheck using Docker

    main

    When running EPUBCheck in a Docker container, you must map a directory from your host machine to the /data path inside the container using a Docker volume. This /data path acts as a bridge to allow the container to access your EPUB files and write output files back to your host.

    Basic Commands

    To view help:

    $ docker run -it --rm -v <directory>:/data epubcheck --help

    To run a check on an EPUB file:

    $ docker run -it --rm -v <directory>:/data epubcheck <epub-file> [OPTIONS]

    Usage Examples

    Example 1: Check a file and print output to console If your file is located at /home/username/file.epub on the host:

    $ docker run -it --rm -v /home/username:/data epubcheck file.epub

    Example 2: Check a file and generate a JSON output file To generate an output file that will be accessible on your host at /home/username/output.json:

    $ docker run - --rm -v /home/username:/data epubcheck file.epub --json output.json

  6. Build EPUBCheck from source

    main

    To build EPUBCheck from the source code, you must have the following installed:

    • Java Development Kit (JDK) 1.7 or above
    • Apache Maven 3.0 or above

    Run the following command to build the project and run tests. This will copy *.jar files and packages to the target/ folder:

    $ mvn clean install

  7. Understand the EPUB 3 XHTML Content Document schema

    main
    The modules in this directory define the vocabulary and grammar for EPUB 3 XHTML Content Documents. This schema is based on W3C HTML but includes specific EPUB extensions. The schemas are derived from the Nu Html Checker (https://validator.github.io/validator/) and are kept up-to-date via a specific commit identifier tracked in the LAST_UPDATE file within this directory.

  8. Understand default validation message severities

    main

    EPUBCheck uses a default mapping to assign a Severity level to each MessageId. These severities determine how validation issues are categorized and reported. The available severity levels include:

    • FATAL: Critical issues that prevent further processing.
    • ERROR: Standard validation errors.
    • WARNING: Potential issues that should be reviewed.
    • INFO: Informational messages.
    • USAGE: Messages related to usage or best practices.
    • SUPPRESSED: Messages that are intentionally not reported (often because they are handled by other rules or are out of scope).

    Validation messages are grouped by category, such as ACC (Accessibility), CSS (Cascading Style Sheets), HTM (HTML), MED (Media), NAV (Navigation), NCX (NCX file), OPF (Open Packaging Format), PKG (Package), RSC (Resources), and SCP (Scripting).

  11. Use EPUBCheck as a Java library

    main

    EPUBCheck can be integrated into Java applications via its public API located in the com.adobe.epubcheck.api package.

    To perform validation programmatically:

    1. Instantiate a validation engine using the EPUBCheck class.
    2. Call the validate() method.
    3. Implement the Report interface to capture and process the list of errors and warnings instead of having them printed to the console.

  12. Understand the CheckerMetadata JSON schema

    main

    When EPUBCheck generates report metadata, it uses the CheckerMetadata structure. This object is intended to be serialized into JSON and provides a summary of the validation run, including file information, checker version, timestamps, execution duration, and a count of different message severities.

    Key JSON fields include:

    • path: The absolute path to the EPUB file (with the working directory removed).
    • filename: The name of the EPUB file.
    • checkerVersion: The version of EPUBCheck used.
    • checkDate: The date and time the check started (formatted as MM-dd-yyyy HH:mm:ss).
    • elapsedTime: The total time taken for the check in seconds.
    • nFatal: Count of fatal messages.
    • nError: Count of error messages.
    • nWarning: Count of warning messages.
    • nUsage: Count of usage messages.