Skip to content

tooltips.md

Latest commit

 

History

History
136 lines (88 loc) · 2.68 KB

tooltips.md

File metadata and controls

136 lines (88 loc) · 2.68 KB
Raw

Tooltips

Tooltips show additional information when hovering over text.

Abbreviations

Define abbreviations that show full text on hover:

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

Add footnotes with references:

DocsForge is a self-contained documentation build system.[^1]

[^1]: All dependencies are vendored into the project repository.

DocsForge is a self-contained documentation build system.1

Content tooltips

Enable with content.tooltips feature:

theme:
  features:
    - content.tooltips

This adds hover tooltips for abbreviations and links throughout the site.

Link tooltips

Use title attribute for link tooltips:

[DocsForge](https://github.com/QQSHI13/docsforge "Self-contained documentation builds")

Definition lists as tooltips

Definition terms can serve as glossary entries:

DocsForge
:   A self-contained documentation build system with vendored dependencies.

Material
:   The most popular documentation theme, built into DocsForge.

DocsForge : A self-contained documentation build system with vendored dependencies.

Material : The most popular documentation theme, built into DocsForge.

Creating a glossary page

Collect all definitions on one page for easy reference:

# Glossary

## A

**API**
:   Application Programming Interface — a set of protocols for building software.

## B

**Build**
:   The process of converting Markdown files into a static HTML site.

## D

**DocsForge**
:   A self-contained documentation engine with vendored dependencies.

Magic links

Automatic link conversion for GitHub references:

See issue #123 and PR #456 for details.

Enable with:

markdown_extensions:
  - pymdownx.magiclink:
      repo_url_shorthand: true
      user: QQSHI13
      repo: docsforge-docs

Link preview tooltips

When content.tooltips is enabled, links to external sites show a preview on hover:

theme:
  features:
    - content.tooltips

Hover over this GitHub link to see a preview.

Best practices

  • Keep abbreviations short and commonly used
  • Write definitions in your own words, not dictionary copies
  • Group related terms in definition lists
  • Test tooltips on mobile (they work differently on touch devices)

Next steps

Footnotes

  1. All dependencies are vendored into the project repository. ↩