Reference
The rules
Fifteen checks across metadata, structure, navigation, and references. Each one describes a specific way an EPUB breaks for assistive technology, and carries the WCAG reference it answers to.
How a book is checked
The pipeline is local unzip, XML and HTML parsing, then a rewrite of the archive. There is no network step.
-
Audit
Unzip the EPUB and run fifteen rules against EPUB Accessibility 1.1 and WCAG 2.x. Output is human-readable, JSON, or SARIF.
-
Fix
Repair metadata, language, alt placeholders, and navigation. Apply every fix, or pass
--onlyfor a subset. -
Verify
Re-audit the repaired archive and return what remains, so a pipeline can fail when a human still needs to make a judgement.
What fix changes
fix writes a repaired EPUB (default <input>.fixed.epub) and logs every change it makes. It applies the fixes below.
- Metadata
- Adds
dc:language,dc:title, and the fiveschema:*accessibility metas when they are missing. - Language
- Sets
langandxml:langon every spine document so assistive technology reads the correct language. - Alt placeholders
- Writes
alt="TODO: describe image"on images with noaltattribute and logs every changed image, so a human can replace the placeholder. - Navigation
- Adds a landmarks nav, builds a page-list when the book has pagebreaks, and generates a whole navigation document, updating the manifest, when the book has none.
The fifteen rules
| Code | Severity | WCAG | Check | Fixable |
|---|---|---|---|---|
E001 | error | 3.1.1 | Missing dc:language | auto |
E002 | error | 2.4.2 | Missing dc:title | auto |
E003 | error | 1.3.1 | Missing schema:accessMode | auto |
E004 | error | 1.3.1 | Missing schema:accessModeSufficient | auto |
E005 | error | 1.3.1 | Missing schema:accessibilityFeature | auto |
E006 | error | 1.3.1 | Missing schema:accessibilityHazard | auto |
W007 | warning | 1.3.1 | Missing schema:accessibilitySummary | auto |
E008 | error | 1.1.1 | Image with no alt attribute | TODO placeholder |
E009 | error | 3.1.1 | <html> without lang / xml:lang | auto |
W010 | warning | 1.3.1 | Navigation missing a landmarks nav | XHTML nav only |
W011 | info / warning | 1.3.1 | Navigation missing a page-list when the book has pagebreaks | when pagebreaks exist |
W012 | warning | 1.3.1 | Headings skip a level or do not begin with an h1 | reported |
W013 | warning | 1.3.1 | Table has no header cells | reported |
W014 | warning | 2.4.4 | Link text is a raw URL | reported |
E015 | error | 2.4.1 | Publication has no navigation document | writes nav + manifest |
The rules reported but not auto-fixed are the ones where a repair would require judgement. Guessing a heading level or a link label silently corrupts the book; booklens leaves those to a human and says so. W010 and W011 can only be written into an XHTML navigation document; for an EPUB 2 / NCX-only book fix skips them with a changelog line instead of corrupting the NCX. W011 is a warning when the book contains pagebreaks and an info note when it does not.
Example run
An audit of a deliberately inaccessible book, as the CLI prints it:
$ booklens audit fixtures/inaccessible.epuberror E008 OEBPS/chapter1.xhtml 1 image(s) missing an alt attribute.error E009 OEBPS/chapter1.xhtml html element is missing both lang and xml:lang attributes.warning W012 OEBPS/chapter1.xhtml Headings skip a level or do not begin with an h1.warning W013 OEBPS/chapter1.xhtml Table has no header cells (no <th> or role="columnheader").warning W014 OEBPS/chapter1.xhtml Link text is a raw URL: https://example.comerror E001 OEBPS/content.opf Publication is missing a dc:language declaration.error E003 OEBPS/content.opf Publication is missing schema:accessMode metadata.warning W010 OEBPS/nav.xhtml Navigation document is missing a landmarks nav element.info W011 OEBPS/nav.xhtml Navigation document has no page-list; the publication contains no pagebreaks.…inaccessible.epub: 10 error(s), 8 warning(s), 1 info