mdbook-hints

mdBook预处理器，用于向您的书籍添加悬停提示（工具提示）。支持Markdown。

使用方法

1. 使用cargo install mdbook-hints命令安装二进制文件
2. 将hints.css和hints.js从/theme/复制到书籍的/theme/目录
3. 如以下所示更新additional-css和additional-js在book.toml中

[output.html]
-additional-css = []
+additional-css = ["./theme/hints.css"]

-additional-js = []
+additional-js = ["./theme/hints.js"]

4. 在book.toml中添加以下行

[preprocessor.hints]

5. 在/theme/index.hbs文件中在自定义JS脚本之前添加以下行

<!-- Here -->
<script src="https://unpkg.com/@popperjs/core@2"></script>
<script src="https://unpkg.com/tippy.js@6"></script>

<!-- Custom JS scripts -->

6. 在书籍根目录中创建hints.toml文件（与book.toml相同的目录）

现在您可以添加提示

# hints.toml
[cat]
hint = "A cat is a small, independent, domesticated feline known for its playful and sometimes mysterious nature. *meow*"

<!-- my-chapter.md -->
My friend has a [kitty](~cat) with 4 legs.

在!符号后添加~将使提示消失（仅提示，[]括号中的文本仍将显示）

[this pizza hint won't show](~!pizza)

如果在Markdown中指定了提示，但它不会出现在hints.toml中，则提示将被忽略，但[]括号中的文本仍将显示（与[](~!ignored)相同）

$ mdbook build
2024-08-08 20:03:53 [INFO] (mdbook::book): Book building has started
-----
Hint for `non-existent-hint` (general/main.md) is missing in hints.toml!
-----
2024-08-08 20:03:53 [INFO] (mdbook::book): Running the html backend

[!NOTE]
Markdown被转换为未转义HTML，因此只有可信赖的用户才能访问hints.toml文件。如果您想禁用工具提示的HTML支持，这将破坏Markdown注释，您可以在/theme/index.js中这样做。

工作原理/如何自定义

预处理器本身只是将文本包装成带有hint类和标识符值的hint属性的span，并在/src/目录中创建hints.json文件。所以这个输入

[meow meow meow](~cat)

生成以下HTML

<span class="hint" hint="cat">meow meow meow</span>

其余所有内容均由 /theme/hints.js 使用在 /theme/index.hbs 文件中添加的 Tippy.js 库进行管理。样式在 /theme/hints.css 文件中定义。

待办事项

• 自动提示指定的单词
• 添加对自定义类的支持