Abbreviations

Abbreviations lets you add tooltip text for acronyms. When a user hovers over the acronym, the term for the acronym displays. In documentation, the standard is to use the full term the first time an acronym appears in a topic, you can then use the acronym for the rest of the topic. But forgetting this is inevitable. So using abbreviations is a solution that ensures your readers can always find the term for an acronym without having to open another tab and searching for it.

Abbreviation in a Topic

You can add abbreviation terms inside a topic. The following example has the terms in this topic file.

The HTML specification is maintained by the W3C.

Abbreviation Auto-Append

Instead of adding abbreviation terms to every topic, you can created a dedicated file for abbreviated terms and then add auto_append to the mkdocs.yml file.

Publishing MD files can be hosted on GH Pages.

Using Abbreviations and Auto-Append

1. Add a new folder at the root level of your documentation folders and name it includes.
2. Create a new file in the includes folder and name it abbreviations.md.

3. Add the abbreviations used in your documentation.

   *[HTML]: Hyper Text Markup Language
   *[W3C]: World Wide Web Consortium
   

4. In the mkdocs.yml file, add the following information.

   markdown_extensions:
       - abbr
       - pymdownx.snippets:
           auto_append:
               - includes/abbreviations.md