Ally: Improve HTML/Web Page Accessibility

Article Type: How To


  • How can instructors fix accessibility errors identified by Ally in HTML content in D2L Brightspace?


  • In D2L Brightspace, Anthology Ally (Ally) may identify accessibility issues with HTML files or web pages but does not currently provide guidance on how to fix these issues. This article describes how to fix some of the most common accessibility errors in HTML content.
  • For detailed instructions on viewing the accessibility score of content in D2L, read Ally: Instructor's Accessibility Score Indicators.
  • If you still have questions, submit a request for an Accessible Document Design Consultation


Your HTML file should have a logical and hierarchical heading structure that does not rely solely on visual formatting to indicate section headings. Proper use of headings makes it easier to scan the page contents and improves navigation for screen reader users.

Empty headings

This most likely means there is an empty or blank line in your file that has been formatted as a heading. In general, you should avoid blank lines as they can cause confusion for screen readers.

  • Review the heading structure in your file, check for any empty lines and remove as needed. Unfortunately the HTML accessibility checker will not identify empty headings.

Invalid heading structure

If you skip heading levels Ally will alert you that the heading structure is invalid. For example, you may have an H1 immediately followed by an H3. It is acceptable to skip backwards heading levels (e.g., H4 followed by H2)

  • Review the headings in your document, adjusting levels as needed. You can run the built in accessibility checker to quickly locate skipped levels.

Heading structure does not begin at one

This alert will appear if the first heading in your file is not Level 1. It will not appear if you have normal paragraph text before your Heading 1, but this should also be avoided.

  • Fix this by adding a Heading level 1 to the beginning of your document, or changing the heading level of your first heading.

Does not contain any headings

Ally may notify you if your HTML content does not contain any headings, particularly if it is a longer page.

  • Add Heading Levels 1 through 4 using the HTML editor in D2L:
    • Highlight text that should be a heading
    • Click the first button in the editor toolbar (it most likely says Paragraph), and select the appropriate heading level from the drop down
  • If you have changed the visual formatting without applying a heading style, the built in accessibility checker can identify text that may be a heading based on the visual appearance. This will require a manual review of any text that is identified as a potential heading.

Set Title and Language

If you receive a notice that "The HTML content is missing a title" or "The HTML content does not have a language set" these can be fixed by setting the page attributes of your HTML content.

  • Begin editing the HTML content in D2L
  • Click on the + symbol in the editor toolbar
  • Select Attributes
  • Click on Page Attributes
  • Enter a Page Title, this can be the same as the document title
  • Enter the correct language code of your file (en = English)
  • Click Create
  • Click Save and Close

Images that are missing a description

All images must have descriptive alternative text or be marked as decorative. View this WebAIM Alternative Text Article for more guidance on writing effective alternative text. If you use the Insert Image button you will need to add alt text before inserting an image into an HTML file. If you paste an image into the HTML editor you will not be prompted to write alternate text but you should still add it.

To add or edit an image description:

  • Edit the HTML file
  • Right click on an image
  • Select Image from the pop up that appears
  • Add descriptive text to the Alternative Description field. If this is a decorative image, leave this blank and select the Image is decorative checkbox.

Table Headers

Table headers are important for enabling screen reader users to understand the data presented in a table. This requires changing the cell properties of the first row and/or first column. Similar to creating a heading structure for your document, this cannot be done with visual formatting alone. Remember that tables should not be used for layout purposes.

Column Headers

  • Select all cells in the first row
  • Open the drop down menu of the table tool icon
  • Select Cell
  • Select Cell Properties
  • In the Cell Type drop down select Header cell
  • In the Scope drop down select Column

Row Headers

  • Select all cells in the first column
  • Open the drop down menu of the table tool icon
  • Select Cell
  • Select Cell Properties
  • In the Cell Type drop down select Header cell
  • In the Scope drop down select Row

Table headers that are missing content

If you have defined a row or column as table headers but some of these cells are blank the accessibility score will include the issue "This HTML file contains table headers that are missing content". Review your tables and be sure that any row and column header cells include content. If there are cells that are intentionally left blank in the header row or column, change the cell properties to Cell Type: Cell and Scope: None.

Contrast Issues

Ally will check if the color contrast in your file is sufficient. The HTML editor also has a built-in color contrast analyzer that you can use when selecting text colors.

  • Begin editing the HTML content
  • Run the Accessibility Checker to locate the text with insufficient contrast
  • Change the text color to something with higher contrast
  • The select color menu will tell you if the currently selected color meets color contrast requirements for small and large text. You should have a green check mark to indicate that your chosen color has sufficient contrast. If you have a red X try a different color or a darker shade of your current color.

Remember that you should not use color as the only means to convey information.

Links with no textual content

This can be difficult to locate and fix; somewhere in your document there is a link that is not associated with any display text. This may happen if you delete link text without fully removing the hyperlink.

  • You may be able to find it by looking for an external link icon that is by itself or not next to any hyperlinked text:
  • Go to Edit HTML and delete the icon and any surrounding blank space
  • You can also fix it by removing the link within the HTML code.

Videos without captions

Ally cannot always verify whether or not a video has captions, so you may get a perfect accessibility score but still have a message that the file contains a video without captions. This is there to remind users to check for captions on their videos, but does not affect the overall score.

Check any videos in your file and make sure there is an option to enable closed captions (cc). If your video does not have captions, submit a Closed Captioning Request.

Print Article


Article ID: 143435
Thu 1/26/23 3:17 PM
Mon 7/10/23 8:58 AM

Related Articles (2)

Ally's integration with D2L allows faculty to quickly see the scores on individual content items within D2L content.
FACULTY: use the built in accessibility checker to make sure HTML files/web pages in D2L are accessible.

Related Services / Offerings (1)

Request consultation for designing accessible documents.