mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-11-24 15:40:15 +01:00
162 lines
4.2 KiB
Markdown
162 lines
4.2 KiB
Markdown
---
|
||
template: overrides/main.html
|
||
icon: material/tooltip-plus
|
||
---
|
||
|
||
# Tooltips
|
||
|
||
Material for MkDocs makes it trivial to add tooltips to links, abbreviations
|
||
and all other elements, which allows for implementing glossary-like
|
||
functionality, as well as small hints that are shown when the user hovers or
|
||
focuses an element.
|
||
|
||
## Configuration
|
||
|
||
This configuration enables support for tooltips and abbreviations and allows to
|
||
build a simple glossary, sourcing definitions from a central location. Add the
|
||
following lines to `mkdocs.yml`:
|
||
|
||
``` yaml
|
||
markdown_extensions:
|
||
- abbr
|
||
- attr_list
|
||
- pymdownx.snippets
|
||
```
|
||
|
||
See additional configuration options:
|
||
|
||
- [Abbreviations]
|
||
- [Attribute Lists]
|
||
- [Snippets]
|
||
|
||
[Abbreviations]: ../setup/extensions/python-markdown.md#abbreviations
|
||
[Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
|
||
[Snippets]: ../setup/extensions/python-markdown-extensions.md#snippets
|
||
|
||
### Improved tooltips
|
||
|
||
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
|
||
[:octicons-tag-24: insiders-4.15.0][Insiders] ·
|
||
:octicons-beaker-24: Experimental
|
||
|
||
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:
|
||
|
||
- __Content__ – elements with a `title`, permalinks and copy-to-clipboard button
|
||
- __Header__ – home button, header title, color palette switch and repository link
|
||
- __Navigation__ – links that are shortened with ellipsis, i.e. `...`
|
||
|
||
[Insiders]: ../insiders/index.md
|
||
|
||
## Usage
|
||
|
||
### Adding tooltips
|
||
|
||
The [Markdown syntax] allows to specify a `title` for each link, which will
|
||
render as a beautiful tooltip when [improved tooltips] are enabled. Add a
|
||
tooltip to a link with the following lines:
|
||
|
||
``` markdown title="Link with tooltip, inline syntax"
|
||
[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:
|
||
|
||
``` markdown title="Link with tooltip, reference syntax"
|
||
[Hover me][example]
|
||
|
||
[example]: https://example.com "I'm a tooltip!"
|
||
```
|
||
|
||
<div class="result" markdown>
|
||
|
||
[Hover me](https://example.com "I'm a tooltip!")
|
||
|
||
</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" }
|
||
|
||
</div>
|
||
|
||
[Markdown syntax]: https://daringfireball.net/projects/markdown/syntax#link
|
||
[improved tooltips]: #improved-tooltips
|
||
|
||
### Adding abbreviations
|
||
|
||
Abbreviations can be defined by using a special syntax similar to [links] and
|
||
[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>
|
||
|
||
[links]: #adding-tooltips
|
||
[footnotes]: footnotes.md
|
||
|
||
### Adding a glossary
|
||
|
||
The [Snippets] extension can be used to implement a simple glossary by moving
|
||
all abbreviations in a dedicated file[^1], and [auto-append] this file to all
|
||
pages with the following configuration:
|
||
|
||
[^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 MkDocs might otherwise complain about an
|
||
unreferenced file.
|
||
|
||
=== ":octicons-file-code-16: includes/abbreviations.md"
|
||
|
||
```` markdown
|
||
*[HTML]: Hyper Text Markup Language
|
||
*[W3C]: World Wide Web Consortium
|
||
````
|
||
|
||
=== ":octicons-file-code-16: mkdocs.yml"
|
||
|
||
```` yaml
|
||
markdown_extensions:
|
||
- pymdownx.snippets:
|
||
auto_append:
|
||
- includes/abbreviations.md
|
||
````
|
||
|
||
[auto-append]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#auto-append-snippets
|