# Tooltips

Technical documentation often incurs the usage of many acronyms, which may need additional explanation, especially for new user of your project. For these matters, Zensical uses a combination of Markdown extensions to enable site-wide glossaries.

## Configuration

This configuration enables abbreviations and allows to build a simple project-wide glossary, sourcing definitions from a central location. Add the following line to your configuration:

```toml
[project.markdown_extensions]
abbr = {}
attr_list = {}
pymdownx.snippets = {}
```

```yaml
markdown_extensions:
  - abbr
  - attr_list
  - pymdownx.snippets
```

See additional configuration options:

- [Abbreviations](<https://zensical.org/docs/compatibility/markdown/python-markdown/#abbreviations>)
- [Attribute Lists](<https://zensical.org/docs/compatibility/markdown/python-markdown/#attribute-lists>)
- [Snippets](<https://zensical.org/docs/compatibility/markdown/python-markdown-extensions/#snippets>)

### Improved tooltips

When improved tooltips are enabled, Zensical replaces the browser's rendering logic for `title` attribute with beautiful little tooltips. Add the following lines to your configuration::

```toml
[project.theme]
features = [
  "content.tooltips",
]
```

```yaml
theme:
  features:
    - content.tooltips
```

Now, tooltips will be rendered for the following elements:

- **Content** – elements with a `title`, permalinks and code copy button
- **Header** – home button, header title, color palette switch and repository link
- **Navigation** – links that are shortened with ellipsis, i.e. `...`

## Usage

### Add a tooltip

The [Markdown syntax](<https://daringfireball.net/projects/markdown/syntax#link>) allows to specify a `title` for each link, which will render as a beautiful tooltip when [improved tooltips](<#improved-tooltips>) are enabled. Add a tooltip to a link with the following lines:

Link with tooltip, inline syntax

```markdown
[Hover me](https://example.com "I'm a tooltip!")
```

[Hover me](<https://example.com> "I'm a tooltip!")

Tooltips can also be added to link references:

Link with tooltip, reference syntax

```markdown
[Hover me][example]

[example]: https://example.com "I'm a tooltip!"
```

[Hover me](<https://example.com> "I'm a tooltip!")

For all other elements, a `title` can be added by using the [Attribute Lists](<https://zensical.org/docs/compatibility/markdown/python-markdown/#attribute-lists>) extension:

Icon with tooltip

```markdown
:material-information-outline:{ title="Important information" }
```

### Add abbreviations

Abbreviations can be defined by using a special syntax similar to URLs and [footnotes](<https://zensical.org/docs/authoring/footnotes/index.md>), starting with a `*` and immediately followed by the term or acronym to be associated in square brackets:

Text with abbreviations

```markdown
The HTML specification is maintained by the W3C.

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

The HTML specification is maintained by the W3C.

### Add a glossary

The [Snippets](<https://zensical.org/docs/compatibility/markdown/python-markdown-extensions/#snippets>) extension can be used to implement a simple glossary by moving all abbreviations in a dedicated file[^/docs/authoring/tooltips/#1], and [auto-append](<https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#auto-append-snippets>) this file to all pages with the following configuration:

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

```toml
[project.markdown_extensions]
pymdownx.snippets.auto_append = [
  "includes/abbreviations.md",
]
```

```yaml
markdown_extensions:
  - pymdownx.snippets:
      auto_append:
        - includes/abbreviations.md
```

[^/docs/authoring/tooltips/#1]: It's highly recommended to put the Markdown file containing the abbreviations outside of the `docs` folder (here, a folder with the name `includes` is used), as Zensical might otherwise complain about a file that is not referenced.