1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
|
---
icon: material/tooltip-plus
---
# 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, Material for MkDocs 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 `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
<!-- md:version 9.5.0 -->
<!-- md:flag 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 code copy button
- __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
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 URLs 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>
[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
!!! 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
````
|
