Possible replacement for EPUBCHECK - Page 5

KevinH · 07-12-2026, 12:28 PM

When on earth did epubcheck start allowing bare text whose direct parent is the body tag under epub3. At one time was an error (even under epub3).

That is definitely not a good epubcheck change, imho. It should still be a warning or usage level at least.

JSWolf · 07-12-2026, 03:18 PM

Quote:

Originally Posted by KevinH

When on earth did epubcheck start allowing bare text whose direct parent is the body tag under epub3. At one time was an error (even under epub3).

That is definitely not a good epubcheck change, imho. It should still be a warning or usage level at least.

I just tested @Doitsu's ePub3 code and epubcheck did not show an error for the bare text. The calibre error checker did show an error.

We've just found a bug in epubcheck.

Kayadelenium · 07-12-2026, 04:53 PM

Quick thought I'd like your take on — not a vote, just curious where I'm wrong.

On Doitsu's second point: it turns out that's an EPUB 2 (XHTML 1.1, block-only body) content-model rule. In EPUB 3 the same markup is valid, so epubveri already matches epubcheck there.

My leaning: rather than build out EPUB 2's older content model, I'd rather put that effort into getting ahead on EPUB 3.4 — new features to validate (AVIF/JXL, Opus/AAC, XHTML-only, TTF, SHA-1 phase-out) that epubcheck doesn't cover yet. New production is EPUB 3, and that's where a validator earns its keep.

So EPUB 2 content-model checks would stay partial (documented), extended later if there's real demand.

@KevinH — you know this landscape better than most: in your world, is EPUB 2 validation still worth deep investment, or is 3.x/3.4 the right bet? Genuinely curious what you'd do.

On a related note — since 0.5.0 epubveri can emit its results as machine-readable JSON (--format json), and the WASM build/browser demo return the same structure. Might be a useful hook for anyone thinking about tooling/editor integration.

KevinH · 07-12-2026, 07:14 PM

As much as I would love to leave epub2 to bitrot, there are still many tools and places (Europe, etc) where epub2 still dominates. So I would focus on epub 3.3 first (not the epub 3.4 extensions that have not been adopted by anyone yet) and then epub2 compliance.

But that is your call.

Yes, the json output should allow a Sigil plugin to be developed to integrate its results right into Sigil's validation window.

KevinH · 07-12-2026, 07:36 PM

Here is why bare text in the body tag is a really bad idea:

Quote:

Yes, bare text is technically allowed directly inside the body tag under modern ⁠HTML5 standards. The specification permits "flow content" within the body, which includes plain text nodes.

However, placing bare text directly in the body is strongly discouraged and considered a poor development practice.

Why You Should Avoid Bare Text

1. No Styling Control: You cannot target bare text with specific CSS rules unless you apply the style to the entire <body> element.

2. Layout Issues: Bare text cannot be easily positioned, flexed, or structured using modern layout tools like CSS Grid or Flexbox.

3. Semantic Weakness: Browsers and screen readers cannot tell if the text is a paragraph, a heading, or a caption. This hurts web accessibility.

4. SEO Disadvantages: Search engine web crawlers rely on semantic tags to rank and understand your content hierarchy.

The Better Approach

Always wrap your text in appropriate structural or semantic elements:

Use <p> for standard paragraphs.
Use <h1> through <h6> for headings.
Use <span> for small, inline text styling.
Use <div> or <section> for grouping content blocks.

I think we should file a bug report with epubcheck and ask them to at least put back a warning for bare text inside the body, at the very least on Accessibility grounds if nothing else.

Update:

I added a bug report: https://github.com/w3c/epubcheck/issues/1671

Please add your 2 cents to that issue, if you feel strongly about it one way or the other.

Kayadelenium · 07-13-2026, 04:16 AM

Two quick updates.

On the bare-text-in-<body> discussion (and Kevin's epubcheck issue #1671): I added a note there in support of a warning-level treatment. Briefly — bare text directly in <body> really is valid HTML / EPUB 3 flow content, so it isn't a validity error; but the accessibility and semantic concerns are real, which is exactly why a usage/warning framed as accessibility guidance fits better than a hard content-model error. I think a warning (as Kevin proposes) is the right call, and epubveri will follow whatever epubcheck lands on here rather than get ahead of it.

epubveri v0.5.3 is out (all channels — prebuilt binaries, crates.io, the browser demo, and npm):
- Deprecated metadata <link rel> keywords — the legacy marc21xml-record / mods-record / onix-record / xmp-record and xml-signature — now draw a warning (OPF-086), matching epubcheck.
- Under the hood, the --format json output types were made reusable across tooling — groundwork toward the kind of editor integration Kevin mentioned (a Sigil plugin reading epubveri's JSON results).

As always, bug reports welcome on GitHub.

JSWolf · 07-13-2026, 07:17 AM

That's good that epubveri warns about bare text in ePub3.

KevinH · 07-13-2026, 07:41 AM

And fwiw, I think the epubcheck using "whatever is valid in html5" as the standard for acceptance, is in general a huge mistake.

Html5 accepts pure slop code that basically has few if any guidelines.

Since epub 3 already requires its xhtml variant, with xml syntax rules (no implied closing tags, no adoption agency spaghetti code, etc) epubcheck should be applying much stricter (best practice) kinds of rules to nudge the user base into better practices in code usage and accessibility.

And Html5 is simply not a workable standard for archival publishing because it and its css are constantly being changed because they are living standards. To make matters worse, Html5 and css change in much shorter cycletimes than would be expected for a published book/epub which should still be readable in decades.

For example, just because modern css now allows native fully nested selectors, does not mean it should be accepted into an epub3. As far as I know the w3c java css validator still rejects it (and I hope it stays that way).

IMHO, epubcheck and other validators should understand their role is to act as gatekeeper and nursemaid to keep pure junk out of the epub marketplace and encourage better and more stable code that will work across all e-readers for decades and has improved Accessibility. Epubs are not websites.

Doitsu · 07-13-2026, 10:58 AM

Quote:

Originally Posted by Kayadelenium

As always, bug reports welcome on GitHub.

Not a bug, but I've found a case where the EPUCheck error messages are more helpful. This is an excerpt from a very poorly formatted book with ordered and unordered lists with missing list items.

Spoiler:

epubveri 0.5.3 simply reports:

ERROR RSC-005: content document does not conform to the EPUB XHTML content-model schema

OTOH, EPUBCheck outputs the line and column numbers of both <p> tags that should have been <li> tags and the <ul> and <ol> tags.

ERROR(RSC-005): Error while parsing file: element "ol" incomplete; missing required element "li"
ERROR(RSC-005): Error while parsing file: element "p" not allowed here; expected element "li"
ERROR(RSC-005): Error while parsing file: element "ul" incomplete; missing required element "li"
ERROR(RSC-005): Error while parsing file: element "p" not allowed here; expected element "li"

EDIT: I've also found a bug: epuberi will output the following error message if META-INF contains com.apple.ibooks.display-options.xml or other unmanifested files.

ERROR PKG-025: 'META-INF/com.apple.ibooks.display-options.xml' is a publication resource stored inside META-INF

The message should be removed or downgraded to INFO severity because META-INF does not contain publication resources.

Kayadelenium · 07-14-2026, 05:18 PM

Quick correction so nobody's surprised: epubveri doesn't warn about bare text in EPUB 3 today. What I said is that I support Kevin's proposal on the epubcheck tracker (a warning framed as accessibility guidance), and that epubveri will implement whatever epubcheck decides there — I don't want to guess a severity that later disagrees with epubcheck's. In EPUB 2 it's a genuine content-model error, and that check is on my list.

@Doitsu — both points from your last post are filed: the missing line:column on those RSC-005 content-model errors (#17 (https://github.com/veripublica/epubveri/issues/17)) and the META-INF flags (#16 (https://github.com/veripublica/epubveri/issues/16)). You're right about META-INF: checking against epubcheck's own test suite, PKG-025 should only fire when a manifest-declared resource lives in META-INF — undeclared metadata files like Apple's display options shouldn't be flagged at all. That's a real false positive; fix is scoped and coming in the next release. Thanks again — your reports keep finding exactly the right spots.

JSWolf · 07-14-2026, 05:38 PM

Quote:

Originally Posted by Kayadelenium

Quick correction so nobody's surprised: epubveri doesn't warn about bare text in EPUB 3 today. What I said is that I support Kevin's proposal on the epubcheck tracker (a warning framed as accessibility guidance), and that epubveri will implement whatever epubcheck decides there — I don't want to guess a severity that later disagrees with epubcheck's. In EPUB 2 it's a genuine content-model error, and that check is on my list.

Why go with what epubcheck goes with if it's wrong? You should warn about bare text for ePub3. If there is bare text, I want to fix it. I want to know it's there. I want the warning. It's an error. But a warning is OK to know to fix it.

Doitsu · 07-15-2026, 01:35 AM

@Kayadelenium:

I've found one more potential false positive:

epubveri will report:

Code:

ERROR RSC-005: An "index" must contain one and only one "index-entry-list"

for this line in a NAV doc:

Code:

<li><a epub:type="index" href="index.xhtml">Index</a></li>

IMHO, the "index must contain exactly one index-entry-list" error should only be reported when epub:type="index" is used in an actual EPUB index.

(EPUBCheck doesn't report this as an error.)

Kayadelenium · 07-15-2026, 05:12 AM

Thanks @Doitsu — both of your reports are addressed in v0.5.5, just released.

The index false positive (your last post): fixed. A nav landmark like <a epub:type="index" href="index.xhtml">Index</a> was being treated as an actual index structure and wrongly required to contain an index-entry-list. It now matches epubcheck: the index content-model is only checked on documents declared as an index in the OPF (a manifest properties="index" item, a document linked from an index <collection>, or dc:type="index"), never on a document that merely contains an epub:type="index" element. A document that really is a declared index is still validated. (issue #19 (https://github.com/veripublica/epubveri/issues/19))

The PKG-025 false positive (undeclared metadata files in META-INF/, e.g. Apple's display-options or calibre's bookmarks) shipped a bit earlier, in v0.5.4. (issue #16 (https://github.com/veripublica/epubveri/issues/16))

Still open — the missing line:column on RSC-005 content-model errors (issue #17 (https://github.com/veripublica/epubveri/issues/17)): that one needs deeper work in the schema engine (it has to report which node failed, not just that the document is invalid), so it's the main focus for the next release rather than this one. v0.5.5 does add a machine-resolvable node path (element_path) to the JSON output for findings that already carry a node, which will dovetail with that work.

Binaries for all platforms are on the v0.5.5 release page (https://github.com/veripublica/epubv...ses/tag/v0.5.5). Thanks again — these reports are exactly what's shaping the tool.

Kayadelenium · 07-15-2026, 05:24 AM

Quote:

Originally Posted by JSWolf

Why go with what epubcheck goes with if it's wrong? You should warn about bare text for ePub3. If there is bare text, I want to fix it. I want to know it's there. I want the warning. It's an error. But a warning is OK to know to fix it.

Fair point, @JSWolf — I don't disagree that bare text is worth knowing about, and a warning to help you find and fix it is a reasonable thing to want.

An honest distinction on where I've landed: for EPUB 2, bare text in <body> is a genuine content-model error, and catching that is on my list — no ambiguity there. For EPUB 3 it's the trickier one, because it's valid HTML5 (so it can't be an error), which makes it exactly the "valid but low-quality" case a warning would be for. That specific question is already open upstream as epubcheck #1671 (https://github.com/w3c/epubcheck/issues/1671) (Kevin filed it), and it hasn't been decided there yet.

I'll be straight with you: I haven't had the time to dig properly through epubcheck's own issue tracker, and I don't want to guess a severity/wording ahead of where they land and then have to walk it back. My plan is to clear my own pile of issues and bugs first, then come back to this one properly. It's not a no — it's a "not yet, and I want to do it right."

Thanks for pushing on it — this is exactly the kind of feedback that's useful to hear.

Kayadelenium · 07-15-2026, 07:43 AM

@Doitsu — quick follow-up: v0.5.6 is out, and it addresses the other half of your report. RSC-005 content-model errors now carry a real line/column (plus a machine-resolvable node path), pointing at the offending element — or attribute — instead of just naming the document. So the missing-<li>-in-<ol>/<ul> case now gives you the exact spot.

Binaries: v0.5.6 release page (https://github.com/veripublica/epubv...ses/tag/v0.5.6). Thanks again for the reports.

07-12-2026, 07:14 PM	#64
KevinH Sigil Developer Posts: 9,800 Karma: 7500000 Join Date: Nov 2009 Device: many	As much as I would love to leave epub2 to bitrot, there are still many tools and places (Europe, etc) where epub2 still dominates. So I would focus on epub 3.3 first (not the epub 3.4 extensions that have not been adopted by anyone yet) and then epub2 compliance. But that is your call. Yes, the json output should allow a Sigil plugin to be developed to integrate its results right into Sigil's validation window. Last edited by KevinH; 07-12-2026 at 07:16 PM.

07-13-2026, 07:41 AM	#68
KevinH Sigil Developer Posts: 9,800 Karma: 7500000 Join Date: Nov 2009 Device: many	And fwiw, I think the epubcheck using "whatever is valid in html5" as the standard for acceptance, is in general a huge mistake. Html5 accepts pure slop code that basically has few if any guidelines. Since epub 3 already requires its xhtml variant, with xml syntax rules (no implied closing tags, no adoption agency spaghetti code, etc) epubcheck should be applying much stricter (best practice) kinds of rules to nudge the user base into better practices in code usage and accessibility. And Html5 is simply not a workable standard for archival publishing because it and its css are constantly being changed because they are living standards. To make matters worse, Html5 and css change in much shorter cycletimes than would be expected for a published book/epub which should still be readable in decades. For example, just because modern css now allows native fully nested selectors, does not mean it should be accepted into an epub3. As far as I know the w3c java css validator still rejects it (and I hope it stays that way). IMHO, epubcheck and other validators should understand their role is to act as gatekeeper and nursemaid to keep pure junk out of the epub marketplace and encourage better and more stable code that will work across all e-readers for decades and has improved Accessibility. Epubs are not websites. Last edited by KevinH; 07-13-2026 at 07:55 AM.

07-15-2026, 01:35 AM	#72
Doitsu Grand Sorcerer Posts: 5,852 Karma: 24222221 Join Date: Dec 2010 Device: Kindle PW2	@Kayadelenium: I've found one more potential false positive: epubveri will report: Code: ERROR RSC-005: An "index" must contain one and only one "index-entry-list" for this line in a NAV doc: Code: <li><a epub:type="index" href="index.xhtml">Index</a></li> IMHO, the "index must contain exactly one index-entry-list" error should only be reported when epub:type="index" is used in an actual EPUB index. (EPUBCheck doesn't report this as an error.)

Similar Threads
Thread	Thread Starter	Forum	Replies	Last Post
EPUBCheck v4.2.6	jhowell	ePub	0	06-30-2021 03:49 PM
EPUBCheck v4.2.5	jhowell	ePub	0	03-23-2021 09:45 AM
EPUBCheck v4.2.4	jhowell	ePub	3	06-24-2020 09:51 AM
EPUBCheck v4.1.1	Doitsu	ePub	2	03-18-2019 10:39 AM
Web-based epubcheck upgraded to epubcheck 1.0.5	kjk	ePub	4	02-09-2010 09:53 PM

07-12-2026, 12:28 PM	#61
KevinH Sigil Developer Posts: 9,800 Karma: 7500000 Join Date: Nov 2009 Device: many	When on earth did epubcheck start allowing bare text whose direct parent is the body tag under epub3. At one time was an error (even under epub3). That is definitely not a good epubcheck change, imho. It should still be a warning or usage level at least.

07-12-2026, 04:53 PM	#63
Kayadelenium Enthusiast Posts: 27 Karma: 100000 Join Date: Jul 2026 Location: Planet Earth Device: Kobo Forma	Quick thought I'd like your take on — not a vote, just curious where I'm wrong. On Doitsu's second point: it turns out that's an EPUB 2 (XHTML 1.1, block-only body) content-model rule. In EPUB 3 the same markup is valid, so epubveri already matches epubcheck there. My leaning: rather than build out EPUB 2's older content model, I'd rather put that effort into getting ahead on EPUB 3.4 — new features to validate (AVIF/JXL, Opus/AAC, XHTML-only, TTF, SHA-1 phase-out) that epubcheck doesn't cover yet. New production is EPUB 3, and that's where a validator earns its keep. So EPUB 2 content-model checks would stay partial (documented), extended later if there's real demand. @KevinH — you know this landscape better than most: in your world, is EPUB 2 validation still worth deep investment, or is 3.x/3.4 the right bet? Genuinely curious what you'd do. On a related note — since 0.5.0 epubveri can emit its results as machine-readable JSON (--format json), and the WASM build/browser demo return the same structure. Might be a useful hook for anyone thinking about tooling/editor integration.

07-13-2026, 04:16 AM	#66
Kayadelenium Enthusiast Posts: 27 Karma: 100000 Join Date: Jul 2026 Location: Planet Earth Device: Kobo Forma	Two quick updates. On the bare-text-in-<body> discussion (and Kevin's epubcheck issue #1671): I added a note there in support of a warning-level treatment. Briefly — bare text directly in <body> really is valid HTML / EPUB 3 flow content, so it isn't a validity error; but the accessibility and semantic concerns are real, which is exactly why a usage/warning framed as accessibility guidance fits better than a hard content-model error. I think a warning (as Kevin proposes) is the right call, and epubveri will follow whatever epubcheck lands on here rather than get ahead of it. epubveri v0.5.3 is out (all channels — prebuilt binaries, crates.io, the browser demo, and npm): - Deprecated metadata <link rel> keywords — the legacy marc21xml-record / mods-record / onix-record / xmp-record and xml-signature — now draw a warning (OPF-086), matching epubcheck. - Under the hood, the --format json output types were made reusable across tooling — groundwork toward the kind of editor integration Kevin mentioned (a Sigil plugin reading epubveri's JSON results). As always, bug reports welcome on GitHub.

07-13-2026, 07:17 AM	#67
JSWolf Resident Curmudgeon Posts: 84,206 Karma: 153715495 Join Date: Nov 2006 Location: Roslindale, Massachusetts Device: Kobo Libra 2, Kobo Aura H2O, PRS-650, PRS-T1, nook STR, PW3	That's good that epubveri warns about bare text in ePub3.

07-14-2026, 05:18 PM	#70
Kayadelenium Enthusiast Posts: 27 Karma: 100000 Join Date: Jul 2026 Location: Planet Earth Device: Kobo Forma	Quick correction so nobody's surprised: epubveri doesn't warn about bare text in EPUB 3 today. What I said is that I support Kevin's proposal on the epubcheck tracker (a warning framed as accessibility guidance), and that epubveri will implement whatever epubcheck decides there — I don't want to guess a severity that later disagrees with epubcheck's. In EPUB 2 it's a genuine content-model error, and that check is on my list. @Doitsu — both points from your last post are filed: the missing line:column on those RSC-005 content-model errors (#17 (https://github.com/veripublica/epubveri/issues/17)) and the META-INF flags (#16 (https://github.com/veripublica/epubveri/issues/16)). You're right about META-INF: checking against epubcheck's own test suite, PKG-025 should only fire when a manifest-declared resource lives in META-INF — undeclared metadata files like Apple's display options shouldn't be flagged at all. That's a real false positive; fix is scoped and coming in the next release. Thanks again — your reports keep finding exactly the right spots.

07-15-2026, 05:12 AM	#73
Kayadelenium Enthusiast Posts: 27 Karma: 100000 Join Date: Jul 2026 Location: Planet Earth Device: Kobo Forma	Thanks @Doitsu — both of your reports are addressed in v0.5.5, just released. The index false positive (your last post): fixed. A nav landmark like <a epub:type="index" href="index.xhtml">Index</a> was being treated as an actual index structure and wrongly required to contain an index-entry-list. It now matches epubcheck: the index content-model is only checked on documents declared as an index in the OPF (a manifest properties="index" item, a document linked from an index <collection>, or dc:type="index"), never on a document that merely contains an epub:type="index" element. A document that really is a declared index is still validated. (issue #19 (https://github.com/veripublica/epubveri/issues/19)) The PKG-025 false positive (undeclared metadata files in META-INF/, e.g. Apple's display-options or calibre's bookmarks) shipped a bit earlier, in v0.5.4. (issue #16 (https://github.com/veripublica/epubveri/issues/16)) Still open — the missing line:column on RSC-005 content-model errors (issue #17 (https://github.com/veripublica/epubveri/issues/17)): that one needs deeper work in the schema engine (it has to report which node failed, not just that the document is invalid), so it's the main focus for the next release rather than this one. v0.5.5 does add a machine-resolvable node path (element_path) to the JSON output for findings that already carry a node, which will dovetail with that work. Binaries for all platforms are on the v0.5.5 release page (https://github.com/veripublica/epubv...ses/tag/v0.5.5). Thanks again — these reports are exactly what's shaping the tool.

07-15-2026, 07:43 AM	#75
Kayadelenium Enthusiast Posts: 27 Karma: 100000 Join Date: Jul 2026 Location: Planet Earth Device: Kobo Forma	@Doitsu — quick follow-up: v0.5.6 is out, and it addresses the other half of your report. RSC-005 content-model errors now carry a real line/column (plus a machine-resolvable node path), pointing at the offending element — or attribute — instead of just naming the document. So the missing-<li>-in-<ol>/<ul> case now gives you the exact spot. Binaries: v0.5.6 release page (https://github.com/veripublica/epubv...ses/tag/v0.5.6). Thanks again for the reports.