Did a “Link to Non-HTML Document” warning appear in an Accessibility Checker audit of one of your WordPress posts or pages? Read on below for an explanation of this warning, how it impacts your website’s accessibility, and how to fix it.
Table of Contents
- About the Link to Non-HTML Document Warning
- Impact on Accessibility
- Why do files I link to need to be accessible?
- What accessibility problems can exist in non-HTML documents?
- Relevant WCAG 2.1 Success Criteria
- 1.1.1 Non-text Content – Level A
- 1.4.1 Use of Color – Level A
- 1.4.3 Contrast (Minimum) – Level AA
- 1.4.5 Images of Text – Level AA
- 1.4.11 Non-Text Contrast – Level AA
- 2.1.1 Keyboard
- 2.4.3 Focus Order – Level A
- 2.4.4 Link Purpose (In Context) – Level A
- 2.4.6 Headings and Labels – Level AA
- 2.4.9 Link Purpose (Link Only) – Level AAA
- 3.1.1 Language of Page – Level A
- How to Resolve a Link to Non-HTML Document
About the Link to Non-HTML Document Warning
What is a non-HTML document?
A non-HTML document is any document that has been created without using HTML, such as PDFs, Microsoft Office or Open Office documents, and Mac Pages files. All of these are examples of files that typically cannot be opened in a browser (with the exception of PDFs) and may require specialized software in order to open or view the file once downloaded.
What does the Link to Non-HTML Document warning mean?
This warning means that one or more of the links on your page is pointed to a file or document that is not a web page. Accessibility Checker has a separate link to PDF warning and link to Microsoft Office files warning; this warning specifically looks for the following documents in links:
- Apple Pages Documents
- Apple Keynote Files
- Corel WordPerfect
- OpenDocument Spreadsheets
- OpenDocument Text
- OpenDocument Presentations
- Rich Text Format
- StarOffice Writer
- StarOffice Calc
- StarOffice ArcScene Documents
- StarOffice Impress
Why does Accessibility Checker flag a warning if non-HTML files are present?
Non-HTML files, Open Office documents and or Keynote presentations, can be great for sharing information with your website visitors, particularly if they need to be editable by the user or in a printable format. However, if not created with accessibility in mind, these files may contain usability errors that make them inaccessible for people using assistive technology.
Accessibility Checker flags a warning when a non-HTML file is lined to in order to remind you to manually test your file for accessibility and to confirm that it conforms to all relevant WCAG guidelines. Accessibility Checker cannot currently scan non-HTML or WordPress content for accessibility, so you must do this manually or using an automated accessibility checking tool specifically designed for that particular software. The warning is also present as an opportunity for you to reconsider linking to the document.
How does Accessibility Checker test for links to non-HTML documents?
While auditing your page or post content, Accessibility Checker will scan all links on the post or page. If a link with a .rtf, .wpd, .ods, .odt, .odp, .sxw, .sxc, .sxd, .sxi, .pages, or .key file extension is found, then a Link to Non-HTML File warning will be flagged.
Impact on Accessibility
Why do files I link to need to be accessible?
Accessibility laws like Section 508 and the Americans with Disabilities Act (ADA) apply not just to websites, but to all communications that organizations have with disabled persons. This means that every document you provide to users on your website must be just as accessible as is your website – whether they are viewing it on their browser or downloading it and opening it in a separate computer program.
Generally, when accessibility is discussed as it relates to files or documents, it is in reference to blind and visually impaired persons being able to read and understand documents with their assistive technology. Additionally, it is also important to make sure that any linked documents have an appropriate reading level for the intended audience and that alternative versions are available for people with cognitive disabilities, if applicable.
As discussed in our PDF accessibility article, having accessible documents will ensure that your business or organization reaches all of its potential customers and that they are able to fully engage with your documents. Whether you have Keynote presentations, WordPerfect documents, or OpenOffice spreadsheets, if they are not accessible you may lose conversions or decrease sales opportunities. You also put your business or organization at risk of an accessibility lawsuit.
What accessibility problems can exist in non-HTML documents?
When you create documents in an alternate word processing, presentation, or spreadsheet program, your final file will only be accessible if you create it in an accessible manner. There are a number of accessibility issues that can be present in non-HTML documents which are very similar to problems that can exist on the web:
- missing headings,
- incorrectly formatted tables or lists,
- missing alternative text on images,
- no document language declaration, and
- confusing or empty hyperlinks.
When creating any document it is very important to use formatting best practices for the platform. If you leave out columns or insert extra spaces or breaks to position text on the page, you risk breaking the content flow causing screen readers to read information out of order or announce the presence of items that are not intended to be read.
It is also important to note that clicking on a link with one of these file extensions likely downloads the file directly to a user’s computer rather than opening it in their browser. This can be confusing for some users, particularly those who are blind or visually impaired and do not see (or hear) that a file was downloaded to their computer. They may think that the link was broken or did not work and will not know how to access the file.
Additionally, the documents checked for in this warning will have to be opened in a software program other than the user’s browser. Many people will not have the software programs required to open these documents on their computer, which will cause an additional barrier for people accessing the information. If they try to open it with a file program they do have, it may not work or may lose any accessibility features that were present in the original file.
Linking to these files may result in you leaving out a number of people who do not have the software.
Relevant WCAG 2.1 Success Criteria
There are a number of success criteria that apply to documents and non-HTML files. Some apply to the link itself, while others apply to the content within the file.
The following are success criteria that are most relevant to the documents listed above, though other criteria may also apply. We recommend that you review WCAG 2.1 to fully determine which criteria may apply to your specific files.
1.1.1 Non-text Content – Level A
All non-text content that is presented to the user has a text alternative that serves the equivalent purpose.
1.4.1 Use of Color – Level A
Color is not used as the only visual means of conveying information, indicating an action, prompting a response, or distinguishing a visual element.
1.4.3 Contrast (Minimum) – Level AA
The visual presentation of text and images of text has a contrast ratio of at least 4.5:1. Large text has a contrast ratio of 3:1. Incidental text that is purely decorative and logos do not have to meet this contrast requirement.
1.4.5 Images of Text – Level AA
If the technologies being used can achieve the visual presentation, text is used to convey information rather than images of text.
1.4.11 Non-Text Contrast – Level AA
This checkpoint specifies that graphical elements need to have a contrast ratio of at least 3:1 against adjacent colors unless the “particular presentation of graphics is essential to the information being conveyed”.
2.1.1 Keyboard
All functionality of the content is operable through a keyboard interface without requiring specific timings for individual keystrokes
2.4.3 Focus Order – Level A
If a page can be navigated sequentially and the navigation sequences affect meaning or operation, focusable components receive focus in an order that preserves meaning and operability.
2.4.4 Link Purpose (In Context) – Level A
The purpose of each link can be determined from the link text alone or from the link text together with its programmatically determined link context, except where the purpose of the link would be ambiguous to users in general.
2.4.6 Headings and Labels – Level AA
Headings and labels describe topic or purpose.
2.4.9 Link Purpose (Link Only) – Level AAA
A mechanism is available to allow the purpose of each link to be identified from link text alone, except where the purpose of the link would be ambiguous to users in general.
3.1.1 Language of Page – Level A
The default human language can be programmatically determined.
How to Resolve a Link to Non-HTML Document
What to do (in short)
To resolve a Link to Non-HTML File Warning, you need to follow these steps:
- If you’re using a WordPress plugin that allows you to embed the document on your website, you need to ensure a direct link to view or download it is also present.
- Ensure the link to the document warns users it is a link to a document of that file type by displaying the specific file extension in the link anchor.
- Test and remediate your file for accessibility errors.
- After determining your file is fully accessible, you can safely “Ignore” the warning in the Accessibility Checker.
Consider adding other alternative file types such as PDFs, MS Office, or Google Drive documents for people who do not have software for the file type you have linked.
How to find and fix linked non-HTML file warnings in WordPress
First, install the free Accessibility Checker WordPress plugin.
For any pages or posts with links to a non-HTML file, you can open the details tab in the Accessibility Checker meta box in the WordPress editor, then expand the Link to Non-HTML File warning to see a list of code that caused the warning to appear.
In the screenshot above, the following code has flagged a Link to Non-HTML File warning:
<a class="wp-block-button__link" href="https://website.com/wp-content/uploads/02/11/resume.pages">Download Resume</a>This particular example is a button that would allow people to download a resume that was created in Apple’s Pages program. If this were your website you would want to ensure that the Pages file is fully accessible and add (.pages) to the link anchor so people know it would download that type of file. With the warning, the updated code would look like this:
<a class="wp-block-button__link" href="https://website.com/wp-content/uploads/02/11/resume.pages">Download Resume (.pages)</a>In an ideal world, you would probably want to rethink providing a .pages version of your resume and should replace this file completely with a different file type such as an accessible PDF that is more widely openable by all users.
Creating accessible files in alternative word processing, presentation, and spreadsheet software
The general accessibility best practices that are described in our Microsoft Office warning article are also relevant to documents created in other software programs. We recommend reviewing the information in the reviewing documents for accessibility section on that page and also referencing our PDF accessibility checklist as some items there will apply as well.
Your ability to create properly accessible documents in OpenOffice, StarOffice, WordPerfect, Pages, and Keynote or other similar programs may be limited depending upon the software and how much effort its developers have put into supporting accessibility.
The Chang School at Ryerson University has an excellent reference for creating accessible office documents with detailed instructions on MS Office, Apple, OpenOffice, Adobe, and Google Docs. This is a great place to start if you’re using one of those programs. Otherwise, here is some information about the state of accessibility in these programs today and resources you may find helpful.
Apple
- Create accessible documents, spreadsheet, or presentations with Pages, Numbers, or Keynote, Apple
- Creating accessible Pages documents, Michigan State University
- Accessibility at Apple
Open Office
- OpenOffice Accessibility Project
- OpenOffice accessibility wiki
- WebAIM article on creating accessible documents with OpenOffice Writer
StarOffice
StarOffice and OpenOffice are suites of software built on the same code base, in some ways similar to WordPress.com and WordPress.org – two different platforms that use the same software. OpenOffice is an open-source product and project that is free for anyone to use. StarOffice is a commercial product that is based on OpenOffice. Since they are built on the same code base, the differences between these two products are minimal and it is likely that the accessibility information that applies to OpenOffice also applies to StarOffice.
RTF Files
RTF (Rich Text Format) files are readable with most all word processing software. Because RTF files may not maintain the original formatting and layout of the source document and all images, including pictures, maps, graphs, logos, etc., are removed, RTF files are almost never going to be accessible. The loss of formatting and lack of headings in an RTF document would may make it challenging for blind or visually impaired users of screen readers to find information quickly in an RTF document. On the other hand, if the document is very short, just a paragraph or two, a plain text format may be accessible.
