User Guide

1. Quick-Start Walkthrough

If this is your first time, follow these three steps to check and fix a document in under two minutes:

2. How to Audit a Document

Supported formats

• Word (.docx) -- full ACB + WCAG rule set (fonts, sizes, spacing, emphasis, headings, margins, document properties)
• Excel (.xlsx) -- sheet names, table headers, merged cells, alt text, color-only data, hyperlink text
• PowerPoint (.pptx) -- slide titles, reading order, alt text, font sizes, speaker notes, chart descriptions
• Markdown (.md) -- heading hierarchy, emphasis violations, link text, alt text, emoji, em-dashes, tables
• PDF (.pdf) -- title, language, tagging, font sizes, font families, scanned pages, bookmarks
• ePub (.epub) -- title, language, navigation, heading hierarchy, alt text, table headers, accessibility metadata, link text, MathML detection. Includes comprehensive DAISY Ace checks (100+ axe-core rules).

Choosing an audit mode

Full Audit (recommended for first use)

Checks every rule applicable to your file type. Gives you the complete picture. Use this until you know your document's common issues.

Quick Audit

Checks only Critical and High severity rules. Use this for a fast pass when you are already familiar with your document's formatting.

Custom Audit

Pick individual rules to check. Useful when you are working on specific issues (e.g., only font rules) or running a targeted re-check.

Step-by-step

1. Go to Audit.
2. Choose your rule categories (ACB Large Print, MS Accessibility Checker, or both).
3. Select an audit mode.
4. Upload your file (500 MB maximum).
5. Click Run Audit.
6. Review the report. Each finding shows the rule ID, severity, location in the document, and a description of what is wrong.

Tip: The audit report groups findings by severity. Tackle Critical issues first -- these make the document unreadable for low-vision users. Then work down through High, Medium, and Low.

3. How to Fix a Document

What gets auto-fixed

Step-by-step

1. Go to Fix.
2. Upload your document.
3. Choose a fix mode (Full, Essentials, or Custom).
4. Click Fix Document.
5. For Word and Markdown: download the corrected file. Your original is untouched.
6. For other formats: review the audit report with step-by-step manual fix instructions.

Tip: The fix mode controls what appears in the report, not what gets corrected. Your Word document always receives all available auto-fixes regardless of mode.

Heading detection controls (Word)

The Fix page includes heading-detection controls so you can balance false positives versus recall for your document style.

• Detect and convert faux headings -- identifies heading-like paragraphs that were not styled as real headings.
• Refine with AI (optional) -- uses local Ollama context analysis for borderline candidates.
• Confidence threshold -- higher values reduce candidate count; lower values capture more possible headings.
• Accuracy mode:
  • Conservative -- fewer false positives (helpful for names, times, short labels like "Agenda")
  • Balanced -- recommended default
  • Thorough -- catches more subtle headings and may require more review

Tip: If names or times are being flagged, switch to Conservative. If true headings are being missed, switch to Thorough.

4. How to Create a Template

A template (.dotx) is the easiest way to start compliant. Every new document you create from this template inherits all ACB formatting automatically.

Step-by-step

1. Go to Template.
2. Enter a document title (or leave blank for the default).
3. Optionally check "Include sample content" if you want to see examples of correct formatting.
4. Check "Add binding margin" if the document will be printed and bound.
5. Click Create Template and save the downloaded .dotx file.
6. In Word, double-click the .dotx file to create a new document based on it.

5. How to Export to HTML

Export converts a Word document to a web page with ACB-compliant CSS already applied. Choose between two output modes:

Standalone HTML

A complete web page with its own CSS file. Upload both files to your web server. Good for dedicated pages, intranet publishing, or email attachments.

CMS Fragment

An HTML snippet with embedded CSS scoped to a wrapper class. Paste it into WordPress, Drupal, or any CMS editor block. The scoped CSS will not conflict with your site theme.

Step-by-step

1. Go to Export.
2. Upload a Word (.docx) file.
3. Optionally set a page title.
4. Choose Standalone or CMS Fragment.
5. Click Export and download your result.

Tip: If your source is Markdown instead of Word, use Convert with the "Accessible web page" option instead.

6. How to Convert Between Formats

The Convert page walks you through a guided, step-by-step process to change your document from one format to another. Two main conversion directions are available, plus optional DAISY Pipeline conversions when installed.

To Markdown (plain text extraction)

Extracts readable text from almost any file. Good for feeding documents into AI tools, creating starting points for documentation, or getting a simple version you can search and copy-paste.

Accepts: Word (.docx), Excel (.xlsx), PowerPoint (.pptx), PDF (.pdf), HTML, CSV, JSON, XML, ePub (.epub), and ZIP files.

To accessible web page (HTML)

Turns a document into a complete, accessible HTML page with ACB Large Print CSS built in. Ready to publish on a website. You control the formatting with three options:

• ACB Large Print formatting (on by default) -- applies Arial font, large text, proper spacing, high contrast, and all other ACB requirements
• Binding margin -- adds extra left margin for printed and bound documents
• Print stylesheet -- includes print-optimized CSS for documents that will be both viewed on screen and printed

Accepts: Markdown (.md), Word (.docx), ePub (.epub), reStructuredText (.rst), OpenDocument (.odt), Rich Text (.rtf).

To EPUB or DAISY (via DAISY Pipeline)

When the DAISY Pipeline is installed on the server, additional conversions become available: Word to EPUB, HTML to EPUB, HTML to DAISY 2.02, and EPUB upgrades. These conversions produce publications optimized for reading systems used by people with print disabilities.

Note: Pipeline conversions appear automatically when the DAISY Pipeline is installed. If you do not see these options, Pipeline is not available on this server instance.

Step-by-step

1. Go to Convert.
2. Step 1: Choose what you want to create -- plain text (Markdown) or an accessible web page (HTML).
3. Step 2: Review the formatting options. The defaults follow ACB guidelines and are recommended for most uses. Adjust only if you have a specific need (binding margins for print, or skipping ACB formatting to add your own CSS later).
4. Step 3: Optionally set a page title (for HTML output only).
5. Step 4: Upload your file.
6. Click Convert My Document and download the result.

Tip: For the best HTML results, start with a well-structured source document that uses proper heading styles, lists, and tables rather than manual formatting with bold text and extra blank lines.

7. Understanding Your Results

Severity levels

Reading the report

Each finding in the audit report includes:

• Rule ID -- a short code like ACB-FONT-FAMILY or EPUB-MISSING-ALT-TEXT. Click the help links to learn more about each rule.
• Severity -- Critical, High, Medium, or Low.
• Location -- where in the document the issue was found (paragraph number, slide number, sheet name, heading text, etc.).
• Description -- what is wrong and why it matters.
• Help links -- links to the DAISY Knowledge Base, Microsoft support, or WCAG documentation for detailed remediation guidance.

8. Common Issues and How to Fix Them

9. Tips by Document Format

10. Recommended Workflows

11. DAISY Accessibility Tools

This toolkit integrates with open source tools from the DAISY Consortium, an international association serving people with print disabilities. Here is how each integration works:

DAISY Ace -- EPUB Accessibility Checker

Ace by DAISY is bundled with the web application and runs 100+ automated accessibility checks on EPUB publications using the axe-core engine. Every ePub audit automatically includes:

• All axe-core HTML accessibility rules (contrast, ARIA, landmarks, tables, forms)
• EPUB-specific metadata validation (accessibility metadata, package structure)
• Content document structure checks (headings, images, links)
• Findings linked to the DAISY Knowledge Base for remediation guidance

DAISY Pipeline -- Document Conversion

DAISY Pipeline performs format conversions optimized for accessible publishing. When installed, the Convert page gains additional options:

• Word (.docx) to EPUB 3
• HTML to EPUB 3
• HTML to DAISY 2.02 (digital talking book format)
• EPUB 2 to EPUB 3 upgrade

DAISY Knowledge Base

The Accessible Publishing Knowledge Base provides the help links you see throughout audit reports. Every ePub-related finding links to a specific Knowledge Base article with detailed remediation guidance.

MathML and Mathematical Content

When ePub files contain MathML (mathematical markup), the audit detects it and provides guidance on making mathematical content accessible. The MathCAT project (Math Capable Assistive Technology) by DAISY generates speech, braille, and navigation from MathML for screen readers. If your ePub uses MathML, ensure it is properly structured so tools like MathCAT and MathJax can process it.

12. Keyboard and Screen Reader Tips

This tool is designed to work fully without a mouse. Here are tips for keyboard and screen reader users:

• Skip link: Press Tab on any page to reveal a "Skip to main content" link that jumps past the navigation.
• Navigation: The main navigation is a list of links. Use Tab and Enter to navigate between pages.
• Forms: All form fields have visible labels and description text. Errors are announced with the alert role.
• Accordions: Help sections use <details>/<summary> elements. Press Enter or Space on a summary to expand or collapse. Screen readers announce the expanded/collapsed state.
• File upload: After selecting a file, Tab to the submit button and press Enter. Upload progress is indicated by the page loading a new result.
• Severity badges: In the audit report, severity levels are shown as colored badges. The text content is always present (not color-only), so screen readers announce "Critical", "High", etc.
• Help links: External help links open in new tabs and are announced as such.
• Back to top: Each section on the Guidelines and Guide pages has a "Back to table of contents" link for quick navigation.

13. Stress Testing and Product Learning

The heading-detection and Word-fixing pipeline is backed by a reproducible synthetic stress harness. It exists for one reason: copied-and-pasted real-world documents rarely arrive clean. The product now exercises 1000 randomized heading scenarios across 1000 generated Word documents, with 1 scenario blocks per document.

The corpus is two-phase by design. Phase 1 pressures faux-heading detection with both genuine headings and intentional false positives. Phase 2 runs the fixing path against the same documents and verifies that repaired output lands back on strict ACB formatting, especially flush-left alignment and zero paragraph indentation unless a configured override is in effect.

Why this matters

• It catches documents that visually resemble headings but were pasted as plain text or manual formatting.
• It forces the fixer to normalize centered titles, justified body text, hanging indents, and mixed fonts back into ACB-compliant large print.
• It turns new failures into product requirements instead of leaving them as one-off test fixtures.

How we validated this release

We run the stress harness in multiple ways so both correctness and repair quality are verified:

1. Targeted full-process validation: generate the 1,000-document corpus and run repair checks across all generated files.
2. Full-suite validation: run the complete heading stress test file to confirm metadata, sampled scenarios, full generation, and full repair behavior all pass together.
3. Ground-truth comparison: compare detector output directly against the known expected headings in the synthetic corpus.
4. Fix-then-audit enforcement validation: repair the generated documents and then audit them again for ACB rule compliance.

Validation command sequence used by maintainers:

python -m pytest desktop/tests/test_heading_stress_corpus.py::test_full_stress_corpus_generates_one_thousand_documents desktop/tests/test_heading_stress_corpus.py::test_full_fixer_stress_corpus_repairs_all_documents -q
python -m pytest desktop/tests/test_heading_stress_corpus.py -q

Latest recorded outcomes were clean: the heading stress suite passed, denser randomized comparisons showed zero false positives and zero false negatives in the measured runs, and the full 1,000-document fix-then-audit sweep ended with zero remaining ACB findings.

What we learned

• Real documents mix problems together. A file may contain plain-text headings, centered titles, copied email text, font drift, and indentation drift all at once.
• False positives matter as much as missed headings. Signature lines, reminders, and similar short phrases are exactly where weak detectors make mistakes.
• Heading detection is only part of the job. The fixer must also normalize the result back to ACB rules, including heading levels and heading text.

How the platform adapted

• We strengthened negative-pattern handling for signatures and callouts.
• We expanded randomness to cover no-style/plain-text negatives, font-only heading cues, and multilingual numbering.
• We added heading normalization in the fixer so converted headings no longer leave ALL CAPS text or skipped heading levels behind.

Scenario families covered

Notepad Paste

Plain-text paste removes styles, so the detector must infer structure from short lines, whitespace, and casing. Detection focus: unstyled heading-like lines. Fixer focus: restoring real heading styles without disturbing body text.

Email Thread

Email subjects, replies, greetings, and signatures routinely look like headings without actually being structural headings. Detection focus: subjects, greetings, and signature false positives. Fixer focus: keeping signatures flush left after repair.

Web Paste

Browser paste often imports mixed font sizes and emphasis that create noisy faux-heading signals. Detection focus: mixed visual weights and numbered callouts. Fixer focus: normalizing font family, size, and italics.

Meeting Agenda

Agendas combine numbered sections, sub-sections, and short procedural lines that should become real headings. Detection focus: numbered heading ladders. Fixer focus: left-aligned heading hierarchy.

Policy Manual

Policies mix long body paragraphs with terse section labels and frequent indentation drift from copied templates. Detection focus: section labels versus body prose. Fixer focus: removing hanging and first-line indents.

Newsletter

Newsletters introduce pull quotes, bylines, and centered titles that can confuse both detection and repair. Detection focus: bylines and callouts. Fixer focus: repairing centered or justified copy to flush left.

Training Handout

Handouts include short prompts, exercises, and answer labels that resemble headings but are not always structural. Detection focus: exercise labels and prompts. Fixer focus: preserving readable emphasis while removing italic and bold body text.

Legal Outline

Legal outlines use nested numbering and indentation patterns that must be preserved semantically, not visually. Detection focus: outline numbering. Fixer focus: converting visual hierarchy into real heading styles.

Report Appendix

Appendices often mix appendix labels, figure captions, and short notes that need strong discrimination. Detection focus: appendix labels versus captions. Fixer focus: keeping appendix content in ACB-compliant body formatting.

Community Flyer

Flyers rely on visual emphasis, centered slogans, and short bursts of text that must be normalized for large print. Detection focus: headline slogans and event details. Fixer focus: repairing decorative layout into strict ACB presentation.

What the 1,000 documents represented

These were not 1,000 copies of the same sample file. They were designed to stand in for the kinds of Word documents people actually upload: meeting agendas, newsletters, policy manuals, legal outlines, training handouts, appendices, email-style documents, and plain-text paste with no proper heading styles.

Each generated file placed the possible heading inside a realistic document context. That meant the platform had to do two things well: decide whether a line was truly a heading, and then repair the document so the final result followed ACB rules for alignment, font, spacing, emphasis, and heading structure.

Strict ACB enforcement: Whenever the corpus generates an ACB-conformant branch, every paragraph is intentionally flush left. Any centered, right-aligned, justified, indented, italicized, or non-Arial branch is treated as a repair scenario and must be corrected by the fixing pipeline.

14. Frequently Asked Questions

15. Getting Help

• Full ACB Large Print Guidelines Reference -- complete rule documentation with related audit rules
• Submit Feedback -- report bugs, request features, or share your experience
• About This Project -- mission, organizations, standards, and open source dependencies
• GitHub Issues -- report bugs or request features on the open source repository
• DAISY Knowledge Base -- remediation guidance for ePub accessibility issues
• Microsoft Accessibility Checker Guide -- Microsoft's guide to the Office accessibility checker