Summary

Structure glossaries using sections and lists to simplify access to the terms.

Techniques

Examples

Example — A basic glossary

<section role="doc-glossary">
   <h2>Glossary of Terms</h1>
   
   <dl>
      <dt>AstroSeneca</dt>
      <dd>
         <p>First Roman philosopher in space.</p>
       </dd>
       …
  </dl>
</section>

Example — A glossary with explicit subheadings for alphabetical categorization

<section role="doc-glossary">
   <h2>Glossary</h2>
   
   <section>
     <h3>A</h3>
     
     <dl>
       <dt>Absorbitron</dt>
       <dd>
         <p>Transformer known to change into a sponge.</p>
       </dd>
       …
     </dl>
   </section>
   
   …
</section>

Example — A glossary with implicit headings

If the sets of terms are only separated by a visual space, use the aria-label attribute to provide a heading for assistive technologies.

<section role="doc-glossary">
   <h2>Glossary</h2>
   
   <section aria-label="A">
     <dl>
       <dt>Anti-oxidants</dt>
       <dd>
         <p>People who dislike oxidants.</p>
       </dd>
       …
     </dl>
   </section>
   
   <section aria-label="B">
     <dl>
       <dt>Beta-Carotene</dt>
       <dd>
         <p>Carotene that is still in a debugging stage.</p>
       </dd>
       …
     </dl>
   </section>
   
   …
</section>

Frequently Asked Questions

Should I follow the EPUB Dictionaries and Glossaries specification?

Following the structuring principles in the document is advised, and the most useful for accessibility are repeated in this page, but the use of epub:type semantics is not necessary. While these semantics may be useful for internal publisher workflows, they do not currently enhance glossaries in reading systems and the epub:type semantics provide no accessibility.

Given the limited uptake of the specification at this time, there is no need to follow the package document identification requirements.

Explanation

Providing a glossary for technical terms and language that is used in uncommon ways is especially helpful for users with learning and cognitive disabilities. Ensure that links are provided from where the terminology is used to the definitions to make it easier for users to look up definitions. It is typically not necessary to link every instance of a glossary term, as such overlinking can affect navigation for users of assistive technologies (i.e., it becomes more difficult to review the links in a document). Consider only linking the first instance in a new section.

To facilitate navigating the alphabetically and numerically related entries of a glossary, use nested section elements. Many glossaries include the number or letter as a heading between each set of entries, but if one is not present or wanted, include the number or letter in an aria-label attribute on the enclosing section so that it can be announced by assistive technologies. Also, without an explicit or implicit heading, assistive technologies often will not provide the ability to move from one section to another (they are treated like purely stylistic elements).

Structure the terms in each section using definition lists. The use of these lists allows users of assistive technologies to jump forward and backward through the list items instead of having to move through each one at a time as would result if paragraphs or similar markup is used.

Related Links