2022-05-08 18:50:57 +03:00
|
|
|
|
---
|
2022-06-19 14:01:44 +03:00
|
|
|
|
icon: material/tooltip-plus
|
2022-08-21 19:55:23 +03:00
|
|
|
|
status: new
|
2022-05-08 18:50:57 +03:00
|
|
|
|
---
|
|
|
|
|
|
2023-01-02 16:13:07 +03:00
|
|
|
|
# Tooltips
|
2022-05-08 18:50:57 +03:00
|
|
|
|
|
2022-09-11 20:25:40 +03:00
|
|
|
|
Technical documentation often incurs the usage of many acronyms, which may
|
|
|
|
|
need additional explanation, especially for new user of your project. For these
|
|
|
|
|
matters, Material for MkDocs uses a combination of Markdown extensions to
|
|
|
|
|
enable site-wide glossaries.
|
2022-05-08 18:50:57 +03:00
|
|
|
|
|
|
|
|
|
## Configuration
|
|
|
|
|
|
2022-09-11 20:25:40 +03:00
|
|
|
|
This configuration enables abbreviations and allows to build a simple
|
|
|
|
|
project-wide glossary, sourcing definitions from a central location. Add the
|
|
|
|
|
following line to `mkdocs.yml`:
|
2022-05-08 18:50:57 +03:00
|
|
|
|
|
|
|
|
|
``` yaml
|
|
|
|
|
markdown_extensions:
|
|
|
|
|
- abbr
|
2022-05-08 19:37:08 +03:00
|
|
|
|
- attr_list
|
2022-05-08 18:50:57 +03:00
|
|
|
|
- pymdownx.snippets
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
See additional configuration options:
|
|
|
|
|
|
2024-01-28 11:51:25 +03:00
|
|
|
|
- [Abbreviations]{ data-preview="" }
|
|
|
|
|
- [Attribute Lists]{ data-preview="" }
|
|
|
|
|
- [Snippets]{ data-preview="" }
|
2022-05-08 18:50:57 +03:00
|
|
|
|
|
|
|
|
|
[Abbreviations]: ../setup/extensions/python-markdown.md#abbreviations
|
2022-05-08 19:37:08 +03:00
|
|
|
|
[Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
|
2022-05-08 18:50:57 +03:00
|
|
|
|
[Snippets]: ../setup/extensions/python-markdown-extensions.md#snippets
|
|
|
|
|
|
2022-06-11 12:09:20 +03:00
|
|
|
|
### Improved tooltips
|
2022-05-08 18:50:57 +03:00
|
|
|
|
|
2023-12-07 13:56:18 +03:00
|
|
|
|
<!-- md:version 9.5.0 -->
|
2023-09-14 20:09:18 +03:00
|
|
|
|
<!-- md:flag experimental -->
|
2022-05-08 18:50:57 +03:00
|
|
|
|
|
|
|
|
|
When improved tooltips are enabled, Material for MkDocs replaces the browser's
|
|
|
|
|
rendering logic for `title` attribute with beautiful little tooltips.
|
|
|
|
|
Add the following lines to `mkdocs.yml`:
|
|
|
|
|
|
|
|
|
|
``` yaml
|
|
|
|
|
theme:
|
|
|
|
|
features:
|
|
|
|
|
- content.tooltips
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Now, tooltips will be rendered for the following elements:
|
|
|
|
|
|
2023-01-02 16:29:16 +03:00
|
|
|
|
- __Content__ – elements with a `title`, permalinks and code copy button
|
2022-05-08 18:50:57 +03:00
|
|
|
|
- __Header__ – home button, header title, color palette switch and repository link
|
|
|
|
|
- __Navigation__ – links that are shortened with ellipsis, i.e. `...`
|
|
|
|
|
|
|
|
|
|
## Usage
|
|
|
|
|
|
|
|
|
|
### Adding tooltips
|
|
|
|
|
|
|
|
|
|
The [Markdown syntax] allows to specify a `title` for each link, which will
|
2023-09-14 20:09:18 +03:00
|
|
|
|
render as a beautiful tooltip when [improved tooltips] are enabled. Add a
|
2022-05-08 19:37:08 +03:00
|
|
|
|
tooltip to a link with the following lines:
|
2022-05-08 18:50:57 +03:00
|
|
|
|
|
2022-05-08 19:37:08 +03:00
|
|
|
|
``` markdown title="Link with tooltip, inline syntax"
|
2022-05-08 18:50:57 +03:00
|
|
|
|
[Hover me](https://example.com "I'm a tooltip!")
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
<div class="result" markdown>
|
|
|
|
|
|
|
|
|
|
[Hover me](https://example.com "I'm a tooltip!")
|
|
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
Tooltips can also be added to link references:
|
|
|
|
|
|
2022-05-08 19:37:08 +03:00
|
|
|
|
``` markdown title="Link with tooltip, reference syntax"
|
2022-05-08 18:50:57 +03:00
|
|
|
|
[Hover me][example]
|
|
|
|
|
|
|
|
|
|
[example]: https://example.com "I'm a tooltip!"
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
<div class="result" markdown>
|
|
|
|
|
|
|
|
|
|
[Hover me](https://example.com "I'm a tooltip!")
|
|
|
|
|
|
2022-05-08 19:37:08 +03:00
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
For all other elements, a `title` can be added by using the [Attribute Lists]
|
|
|
|
|
extension:
|
|
|
|
|
|
|
|
|
|
``` markdown title="Icon with tooltip"
|
|
|
|
|
:material-information-outline:{ title="Important information" }
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
<div class="result" markdown>
|
|
|
|
|
|
|
|
|
|
:material-information-outline:{ title="Important information" }
|
|
|
|
|
|
2022-05-08 18:50:57 +03:00
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
[Markdown syntax]: https://daringfireball.net/projects/markdown/syntax#link
|
|
|
|
|
[improved tooltips]: #improved-tooltips
|
|
|
|
|
|
|
|
|
|
### Adding abbreviations
|
|
|
|
|
|
2023-09-14 20:09:18 +03:00
|
|
|
|
Abbreviations can be defined by using a special syntax similar to URLs and
|
2022-05-08 18:50:57 +03:00
|
|
|
|
[footnotes], starting with a `*` and immediately followed by the term or
|
|
|
|
|
acronym to be associated in square brackets:
|
|
|
|
|
|
|
|
|
|
``` markdown title="Text with abbreviations"
|
|
|
|
|
The HTML specification is maintained by the W3C.
|
|
|
|
|
|
|
|
|
|
*[HTML]: Hyper Text Markup Language
|
|
|
|
|
*[W3C]: World Wide Web Consortium
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
<div class="result" markdown>
|
|
|
|
|
|
|
|
|
|
The HTML specification is maintained by the W3C.
|
|
|
|
|
|
|
|
|
|
*[HTML]: Hyper Text Markup Language
|
|
|
|
|
*[W3C]: World Wide Web Consortium
|
|
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
[footnotes]: footnotes.md
|
|
|
|
|
|
|
|
|
|
### Adding a glossary
|
|
|
|
|
|
|
|
|
|
The [Snippets] extension can be used to implement a simple glossary by moving
|
2022-06-04 16:33:44 +03:00
|
|
|
|
all abbreviations in a dedicated file[^1], and [auto-append] this file to all
|
|
|
|
|
pages with the following configuration:
|
2022-05-08 18:50:57 +03:00
|
|
|
|
|
|
|
|
|
[^1]:
|
|
|
|
|
It's highly recommended to put the Markdown file containing the
|
2023-09-14 20:09:18 +03:00
|
|
|
|
abbreviations outside of the `docs` folder (here, a folder with the name
|
2022-05-08 18:50:57 +03:00
|
|
|
|
`includes` is used), as MkDocs might otherwise complain about an
|
|
|
|
|
unreferenced file.
|
|
|
|
|
|
2022-09-11 20:25:40 +03:00
|
|
|
|
=== ":octicons-file-code-16: `includes/abbreviations.md`"
|
2022-05-08 18:50:57 +03:00
|
|
|
|
|
|
|
|
|
```` markdown
|
|
|
|
|
*[HTML]: Hyper Text Markup Language
|
|
|
|
|
*[W3C]: World Wide Web Consortium
|
|
|
|
|
````
|
|
|
|
|
|
2022-09-11 20:25:40 +03:00
|
|
|
|
=== ":octicons-file-code-16: `mkdocs.yml`"
|
2022-06-04 16:26:56 +03:00
|
|
|
|
|
|
|
|
|
```` yaml
|
|
|
|
|
markdown_extensions:
|
|
|
|
|
- pymdownx.snippets:
|
|
|
|
|
auto_append:
|
|
|
|
|
- includes/abbreviations.md
|
|
|
|
|
````
|
|
|
|
|
|
|
|
|
|
[auto-append]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#auto-append-snippets
|
2023-12-07 19:20:10 +03:00
|
|
|
|
|
|
|
|
|
!!! tip
|
|
|
|
|
|
|
|
|
|
When using a dedicated file outside of the `docs` folder, add the parent directory to the list
|
|
|
|
|
of `watch` folders so that when the glossary file is updated, the project is automatically
|
|
|
|
|
reloaded when running `mkdocs serve`.
|
|
|
|
|
|
|
|
|
|
```` yaml
|
|
|
|
|
watch:
|
|
|
|
|
- includes
|
|
|
|
|
````
|