Export
From Zacess main at 2bc7be2. Edit this page on GitHub
How a document plus a reading profile becomes accessible output. The code lives in
crates/zacess-core/src/export.
cargo run -p zacess-core --example export -- tests/fixtures/slides-signals.pdf out/ low-visionHTML
One standalone page: the profile's style sheet inline, the document inside <main>, the language
on <html> and real structure throughout.
| Block | Markup |
|---|---|
| Heading | <h1> to <h6>. Levels never skip, so a document whose first heading is level 2 starts at <h1> and nothing jumps from <h2> to <h4> |
| Paragraph | <p>. A quotation is a <p> inside <blockquote> and code is <pre><code> with its spacing kept |
| List | <ul> or <ol> with nested lists inside their <li> |
| Table | <table> with <caption>, <thead> for leading header rows, <th scope="col"> and <th scope="row">, colspan and rowspan |
| Image | <figure><img alt="…"/></figure>. An image with no description yet says so in its alt text rather than being silent. One whose file cannot be found is described in a <figcaption> instead |
| Equation | <math> with presentation MathML built from the recognised equation and the original kept in an <annotation>; display="block" when set on its own line |
| Page break | <hr role="doc-pagebreak" aria-label="Page N"/>, invisible but present, so a screen reader can announce and navigate pages |
Every block carries id="b<id>" from the document model, so a link can point at any block. A run
with a link becomes <a href> when the address is a web, mail or in-page one. Any other address is
left out, so a captured javascript: link can never run from an export.
Low-confidence text
A run that needs checking is wrapped as
<span class="zc-uncertain" data-confidence="0.86"><span class="zc-sr">unclear: </span>kQ</span>The outer span is highlighted by the profile's style sheet with a background that keeps AAA contrast and a dotted underline, so colour is never the only signal. The inner span is visually hidden text, so a screen reader reads "unclear: kQ" and the person knows to check it. A run that has been confirmed or corrected is plain.
Checked against WCAG 2.2 AA
tools/accessibility/check.mjs loads exported pages in headless Chromium and runs axe-core with the
WCAG 2.0, 2.1 and 2.2 A and AA rule sets, failing on any violation. CI runs it on the exported
fixtures and the example document, which covers every block type.
cd tools/accessibility && npm ci && npx playwright install chromium
node check.mjs ../../out/*.htmlEPUB 3
A stored ZIP container with mimetype first, holding:
| File | Contents |
|---|---|
META-INF/container.xml |
Points at the package file |
EPUB/package.opf |
Title, language, a stable identifier derived from the document, dcterms:modified and schema.org accessibility metadata: access modes, features (structural navigation, reading order, table of contents, page break markers, MathML and alternative text when every image has one), hazards and a summary |
EPUB/nav.xhtml |
A table of contents nested by heading level and a hidden page list linking every page marker |
EPUB/content.xhtml |
The same body as the HTML export, serialised as XHTML with epub:type="pagebreak" on the page markers |
EPUB/style.css |
The profile's style sheet |
| Images | Bundled when their files are found next to the source, with the manifest entry each needs |
The content document declares the mathml property when it holds an equation, as EPUBCheck requires.
Checked with EPUBCheck
A unit test runs EPUBCheck on the example document whenever EPUBCHECK_JAR points at
epubcheck.jar. CI runs it on every exported fixture with warnings treated as failures.
EPUBCHECK_JAR=/path/to/epubcheck.jar cargo test -p zacess-core exportBraille
Braille-ready files are described in braille.md.