Skip to content

Adding Abbreviation to MkDocs (with Material for MkDocs)

Context

When writing MkDocs notes, author wants to mark up an abbreviation so that a tooltip with description will pop up when the reader mouse over the abbreviation.

For example, when user mouse over the abbreviation "DSP", user will see a tooltip showing "Digital Signal Processing."

Problem

How to add the description to the abbreviations in the MkDocs notes?

Solution

There are 3 solutions for 3 different scopes:

  1. Use HTML tag <abbr> for individual abbreviation
  2. Use markdown_extension abbr to mark up all the abbreviations in a note
  3. Use markdown_extension abbr and pymdownx.snippets to mark up all the abbreviations in all notes

Using HTML Tag <abbr>

Author can use HTML tag <abbr> to mark up an individual abbreviation like HMM using the following syntax

<abbr title="Hidden Markov Model">HMM</abbr>

This solution will not mark up the other HMM that do not have the <abbr> tag.

Using markdown_extension abbr

When an abbreviation is repeatedly used in a note, author may want to define the description of the abbreviation once, and let MkDocs automatically mark up all the instances in the note. This can be done by the following steps:

  1. Add the following configurations to mkdocs.yml

    markdown_extensions:
  - abbr

  2. In the individual note, define the abbreviations like the following examples:

    The abbreviations like EC and DSP will then have a tooltip showing the corresponding descriptions. This applies to all the mentions of DSP in this note.

*[EC]: Echo Cancellation
*[DSP]: Digital Signal Processing

The abbreviations like EC and DSP will then have a tooltip showing the corresponding descriptions. This applies to all the mentions of DSP in this note.

Using markdown_extension abbr and pymdownx.snippets

When an abbreviation is repeatedly used in multiple notes, author may want to define the description of the abbreviation once, and let MkDocs automatically mark up all the instances in all the notes. This can be done by the following steps:

  1. Create a file at the root of the MkDocs project (which is the directory that contains mkdocs.yml). We will refer to this file as abbreviations.md in the following steps.
  2. Define all the abbreviations in abbreviations.md

  3. Add the following configurations to mkdocs.yml

    markdown_extensions:
  - abbr
  - attr_list
  - pymdownx.snippets:
      auto_append:
        - abbreviations.md

YYC note

What step 3 does is to use the auto_append feature from Snippets to append abbreviations.md to all the notes. Whether the increased size of abbreviations.md affects the site performance is to be reviewed.

Reference