diff --git a/CHANGELOG b/CHANGELOG index bbc760d36..d8f2dcbe1 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,3 +1,12 @@ +mkdocs-material-8.2.14+insiders-4.15.0 (2022-05-08) + + * Added support for improved tooltips + +mkdocs-material-8.2.14 (2022-05-08) + + * Fixed missing top right rounded border on admonition + * Fixed #3886: 4xx status codes not handled when using instant loading + mkdocs-material-8.2.13+insiders-4.14.0 (2022-05-05) * Added Chinese language support to built-in search plugin diff --git a/README.md b/README.md index 4f2358c7d..dbcc7bd41 100644 --- a/README.md +++ b/README.md @@ -147,7 +147,7 @@ Material for MkDocs can be installed with `pip`: pip install mkdocs-material ``` -Add the following line to `mkdocs.yml`: +Add the following lines to `mkdocs.yml`: ``` yaml theme: diff --git a/docs/reference/abbreviations.md b/docs/reference/abbreviations.md deleted file mode 100644 index e171a1d61..000000000 --- a/docs/reference/abbreviations.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -template: overrides/main.html -icon: material/image-size-select-small ---- - -# Abbreviations - -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 - - pymdownx.snippets -``` - -See additional configuration options: - -- [Abbreviations] -- [Snippets] - - [Abbreviations]: ../setup/extensions/python-markdown.md#abbreviations - [Snippets]: ../setup/extensions/python-markdown-extensions.md#snippets - -## Usage - -### 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 -``` - -
- -The HTML specification is maintained by the W3C. - -*[HTML]: Hyper Text Markup Language -*[W3C]: World Wide Web Consortium - -
- - [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 embedding it with the -[`--8<--` notation][Snippets notation] at the end of each document: - - [^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: docs/example.md" - - ```` markdown - The HTML specification is maintained by the W3C. - - --8<-- "includes/abbreviations.md" - ```` - -=== ":octicons-file-code-16: includes/abbreviations.md" - - ```` markdown - *[HTML]: Hyper Text Markup Language - *[W3C]: World Wide Web Consortium - ```` - - [Snippets notation]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#snippets-notation diff --git a/docs/reference/mathjax.md b/docs/reference/mathjax.md index dd4c99738..dbc3d7bb3 100644 --- a/docs/reference/mathjax.md +++ b/docs/reference/mathjax.md @@ -1,6 +1,6 @@ --- template: overrides/main.html -icon: material/alphabet-greek +icon: material/math-integral --- # MathJax diff --git a/docs/reference/tooltips.md b/docs/reference/tooltips.md new file mode 100644 index 000000000..266636612 --- /dev/null +++ b/docs/reference/tooltips.md @@ -0,0 +1,144 @@ +--- +template: overrides/main.html +icon: material/comment-processing-outline +--- + +# 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 + - pymdownx.snippets +``` + +See additional configuration options: + +- [Abbreviations] +- [Snippets] + + [Abbreviations]: ../setup/extensions/python-markdown.md#abbreviations + [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 an link with the following lines: + +``` markdown title="Link with title, inline syntax" +[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: + +``` markdown title="Link with title, reference syntax" +[Hover me][example] + + [example]: https://example.com "I'm a tooltip!" +``` + +
+ +[Hover me](https://example.com "I'm a tooltip!") + +
+ + [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 +``` + +
+ +The HTML specification is maintained by the W3C. + +*[HTML]: Hyper Text Markup Language +*[W3C]: World Wide Web Consortium + +
+ + [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 embedding it with the +[`--8<--` notation][Snippets notation] at the end of each document: + + [^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: docs/example.md" + + ```` markdown + The HTML specification is maintained by the W3C. + + --8<-- "includes/abbreviations.md" + ```` + +=== ":octicons-file-code-16: includes/abbreviations.md" + + ```` markdown + *[HTML]: Hyper Text Markup Language + *[W3C]: World Wide Web Consortium + ```` + + [Snippets notation]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#snippets-notation diff --git a/docs/schema/theme.json b/docs/schema/theme.json index 702618573..0697ca9a9 100644 --- a/docs/schema/theme.json +++ b/docs/schema/theme.json @@ -557,6 +557,13 @@ "content.tabs.link" ] }, + { + "title": "Improved tooltips", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/tooltips/#improved-tooltips", + "enum": [ + "content.tooltips" + ] + }, { "title": "Header hides automatically when scrolling", "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-the-header/#automatic-hiding", diff --git a/docs/setup/changing-the-colors.md b/docs/setup/changing-the-colors.md index 7b81f42a8..d030e2501 100644 --- a/docs/setup/changing-the-colors.md +++ b/docs/setup/changing-the-colors.md @@ -179,11 +179,11 @@ theme: palette: # (1)! - scheme: default toggle: - icon: material/toggle-switch-off-outline # (2)! + icon: material/toggle-switch # (2)! name: Switch to dark mode - scheme: slate # (3)! toggle: - icon: material/toggle-switch + icon: material/toggle-switch-off-outline name: Switch to light mode ``` @@ -214,11 +214,11 @@ The following properties must be set for each toggle: This property must point to a valid icon path referencing any icon bundled with the theme, or the build will not succeed. Some popular combinations: - * :material-toggle-switch-off-outline: + :material-toggle-switch: – `material/toggle-switch-off-outline` + `material/toggle-switch` - * :material-weather-sunny: + :material-weather-night: – `material/weather-sunny` + `material/weather-night` - * :material-eye-outline: + :material-eye: – `material/eye-outline` + `material/eye` - * :material-lightbulb-outline: + :material-lightbulb: – `material/lightbulb-outline` + `material/lightbulb` - * :material-brightness-4: + :material-brightness-7: – `material/brightness-4` + `material/brightness-7` + * :material-toggle-switch: + :material-toggle-switch-off-outline: – `material/toggle-switch` + `material/toggle-switch-off-outline` + * :material-weather-night: + :material-weather-sunny: – `material/weather-night` + `material/weather-sunny` + * :material-eye: + :material-eye-outline: – `material/eye` + `material/eye-outline` + * :material-lightbulb: + :material-lightbulb-outline: – `material/lightbulb` + `material/lightbulb-outline` + * :material-brightness-7: + :material-brightness-4: – `material/brightness-7` + `material/brightness-4` `name`{ #toggle-name } diff --git a/material/base.html b/material/base.html index afbe6b792..104c1c59f 100644 --- a/material/base.html +++ b/material/base.html @@ -22,7 +22,7 @@ {% endif %} - + {% endblock %} {% block htmltitle %} {% if page and page.meta and page.meta.title %} diff --git a/mkdocs.yml b/mkdocs.yml index 81d25f929..0b80ed497 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -51,6 +51,7 @@ theme: features: - content.code.annotate # - content.tabs.link + - content.tooltips # - header.autohide # - navigation.expand - navigation.indexes @@ -73,8 +74,8 @@ theme: icon: material/toggle-switch name: Switch to dark mode - scheme: slate - primary: red - accent: red + primary: indigo + accent: indigo toggle: icon: material/toggle-switch-off-outline name: Switch to light mode @@ -92,6 +93,7 @@ plugins: redirect_maps: changelog/insiders.md: insiders/changelog.md conventions.md: philosophy.md + reference/abbreviations.md: reference/tooltips.md reference/meta-tags.md: reference/index.md reference/variables.md: https://mkdocs-macros-plugin.readthedocs.io/ sponsorship.md: insiders/index.md @@ -195,7 +197,6 @@ nav: - Python Markdown Extensions: setup/extensions/python-markdown-extensions.md - Reference: - reference/index.md - - Abbreviations: reference/abbreviations.md - Admonitions: reference/admonitions.md - Annotations: reference/annotations.md - Buttons: reference/buttons.md @@ -210,6 +211,7 @@ nav: - Images: reference/images.md - Lists: reference/lists.md - MathJax: reference/mathjax.md + - Tooltips: reference/tooltips.md - Insiders: - insiders/index.md - Getting started: diff --git a/package-lock.json b/package-lock.json index 38ba96307..95778a49d 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "mkdocs-material", - "version": "8.2.13", + "version": "8.2.14", "lockfileVersion": 2, "requires": true, "packages": { "": { "name": "mkdocs-material", - "version": "8.2.13", + "version": "8.2.14", "license": "MIT", "dependencies": { "array-flat-polyfill": "^1.0.1", diff --git a/package.json b/package.json index 3724af1f2..e261da67b 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "mkdocs-material", - "version": "8.2.13", + "version": "8.2.14", "description": "Documentation that simply works", "keywords": [ "mkdocs",