mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-11-14 19:07:41 +01:00

2022-06-19 13:01:44 +02:00

4.2 KiB

Raw Blame History

template	icon
overrides/main.html	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:

markdown_extensions:
  - abbr
  - attr_list
  - pymdownx.snippets

See additional configuration options:

Improved tooltips

:octicons-heart-fill-24:{ .mdx-heart } Sponsors only{ .mdx-insiders } · :octicons-tag-24: insiders-4.15.0 · :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:

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. ...

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:

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

Hover me

Tooltips can also be added to link references:

[Hover me][example]

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

Hover me

For all other elements, a title can be added by using the Attribute Lists extension:

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

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

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:

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.

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

Adding a glossary

The Snippets extension can be used to implement a simple glossary by moving all abbreviations in a dedicated file¹, and auto-append this file to all pages with the following configuration:

=== ":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
````

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. ↩︎

4.2 KiB Raw Blame History Unescape Escape