6. 使用实时引用功能构建网站

关于使用 公式引用插件 构建具有实时引用功能的完整网站，可以直接在网站文档教程中找到示例，完整网站的源代码请查看网站源代码。

1. 简介

(1) 如何构建带引用功能的网页笔记仓库？

我们在 v1.3.5 版本 中添加了对网页笔记支持。由于构建一个支持所有多重/连续引用和跨文件预览功能的 Markdown-it 扩展并非易事，就像 公式引用插件 一样。在基于网页的笔记导出中，我们可以使用元素渲染的引用，这需要 批量导出带有引用元数据的 Markdown 文件。

我们的解决方案是指定一个网页笔记导出文件夹，并提供批量导出命令将笔记同步到网页笔记文件夹中。要指定它，请使用 设置 > 分类 > PDF 导出 > 网站笔记导出文件夹。在设置为导出文件夹之前，你应该确保该文件夹是空的。

为确保路径正确解析，请确保所有链接 使用相对于仓库文件夹的相对路径。这在 设置 > 文件与链接 > 新链接格式 中设置。如果你使用最短路径，则需要更新所有链接。

(2) 运行批量导出之前

要确保元数据被保留，请仔细检查 设置 > 分类 > PDF 导出 下的设置：

• 导出的 Markdown 中注入引用元数据 必须选中，以确保必要的元数据被注入到导出的元素中
• PDF 中添加图片标题 和 PDF 中添加图片描述 通常应取消选中。因为最好单独指定标题/描述渲染的样式。
• PDF 保留图片间距 通常应选中，因为许多 Markdown-it 渲染器会将图片与附近文本渲染为同一行。

在导出到网站的过程中，我们只导出 Markdown 文件及其引用的附件。

还有另外 2 个设置：

• 直接复制的 Markdown 文件模式：我们使用 $\ref{}$ 语法解析图片和引用。但对于像 excalidraw Markdown 这样的文件，这些文件不应该被处理。因此我们可以指定需要直接复制的 Markdown 文件格式。
• 排除的网站笔记文件夹：对于一些辅助文件夹，如果你不想一起导出它们，可以指定不需要导出的文件夹。然而，默认情况下，如果有链接指向被排除的文件夹，其中的文件将被视为附件并仍然被导出。因此，你可以对特定文件夹开启 完全忽略链接文件，以在存在链接时忽略这些文件夹中的文件。

然后，你可以将 一个文件/一个文件夹/整个仓库 同步到目标网站导出文件夹。

• 运行命令 同步仓库到网站笔记文件夹 以批量导出仓库中的所有笔记。
• 如果你的仓库太大，只想同步一个文件，运行命令 同步当前文件到网站笔记文件夹。
• 在 文件 树中右键单击文件夹/文件，选择 同步文件/文件夹到网站笔记文件夹。

导出时，本插件将创建一个 .equation-citator-export-index.json 文件来跟踪已导出的文件。不在该列表中的文件在下次导出时不会被删除。

(3) 使用 npm 包解析引用

为解析元数据，我们构建了一个 npm 包 来解析链接并将预览注入到网页中。此包包含 Markdown-it 插件 和 运行时扩展。此包为你提供以下功能：

• Markdown-it 子包

  • Markdown-it 的构建时集成。
  • 为公式、图表和标注添加包装器和目标元数据。
  • 从公式标签或注入的元数据生成稳定的 ID。
  • 解析 Obsidian 链接、嵌入和跨文件引用 URL。

• 运行时子包

  • 用于交互式引用的浏览器运行时。
  • 在页面加载后分配稳定的目标 ID。
  • 解析同页和跨文件引用目标。
  • 提供悬停预览、预览导航和跳转到目标的行为。

注意兼容性：equation-citator-webnote（npm 包）v1.3.xx 与 obsidian-equation-citator v1.3.x 兼容。

你可以通过以下方式安装：

npm i @friedparrot/equation-citator

你需要使用以下内容：

md.use(equationCitatorMarkdownIt, {
  pathMapping: [
    // 仓库的网站链接路径 - 相对于项目文件夹的绝对仓库路径
    { 'your-website.com/knowledge-base': 'docs/knowledge-base' }
  ]
})

我们注意到你可能还需要确保选项 logEmbedLinkRemapping: true 以确保所有图片链接正确。

runtime.js 和 runtime.js.map 文件应在构建网站时复制到资源目录中。

此外，由于此包具有自动 ID 生成和链接映射功能，在网站构建过程中我们需要使用以下规则：

1. 对于 Markdown 的网页 url，使用转义链接：/tutorials/en/2.%20Get%20Started/index.html#_1-4-interactive-features
2. 对于标题的 id 生成，我们暴露了一个 buildHeadingId 函数，你可以通过以下方式使用：

import { buildHeadingId } from 'equation-citator'

const id = buildHeadingId('我的标题')