Inkstone Markdown语法实战:WikiLink、Callout、数学公式与Mermaid图表,10种技巧完整解析

Inkstone 是运行在 Cloudflare Workers 上的自托管 Markdown 笔记应用，正文始终是普通文本，但在此基础上内置了一套强大的 Markdown 扩展语法。本篇教程精选 10 个实战技巧，从 WikiLink 双链、Callout 提示块，到 KaTeX 数学公式与 Mermaid 图表，带你快速把笔记写得既专业又好读。

一、Inkstone 的 Markdown 能力全景

在标准 GFM（表格、任务列表、链接）之外，Inkstone 的渲染管线额外支持以下扩展，全部在预览中即时生效：

类别	语法	效果
笔记关系	[[双链]]、^块ID、((块引用))、![[嵌入]]	双链导航、精确定位、内容嵌入
视觉组件	[!NOTE]Callout、::: details、:::: tabs	提示块、折叠、标签页
学术表达	$行内公式$、$$块公式$$	KaTeX 渲染
图表	`

[[欢迎使用 Inkstone#Markdown 速查|跳到速查表]]

点击链接即可在编辑器中打开目标。所有 WikiLink 会被自动索引，在侧边栏的反向链接面板和关系图谱中可以看到笔记之间的完整关联。解析规则可在 [renderer.ts#L271-L283](https://link.gitcode.com/i/7179cdc0b7277026512d90477c7716c1#L271-L283) 查看，标题匹配不区分大小写和空格，写错一两个空格也能正确跳转。 ## 三、技巧 2：块 ID 与块引用，精确到某一行 想让链接指向笔记中的"某一段"而不是整个笔记？在段落末尾加一个 `^块ID`：

这是重点结论，值得被反复引用。 ^核心结论

然后有两种引用方式： - `[[#^核心结论]]` —— 双链形式，跨笔记跳到这个块 - `((核心结论))` —— 行内块引用，适合在同一段文字中轻量指向 块 ID 支持字母、数字、下划线和连字符（最长 64 字符）。Inkstone 会自动处理重名冲突，给重复 ID 追加序号，你不必手动维护唯一性。 ## 四、技巧 3：把别的笔记整段嵌入当前笔记 `![[ ]]` 是 WikiLink 的"嵌入版"，会把目标内容直接渲染在当前页面： - `![[读书笔记]]` —— 嵌入整篇笔记 - `![[#^核心结论|关键摘录]]` —— 只嵌入一个块，并可自定义标题 嵌入内容会随源笔记实时更新，相当于"活引用"。这比复制粘贴强得多：修改源笔记一次，所有引用处同步生效。 ## 五、技巧 4：用 Callout 打造醒目的提示块 Callout 基于引用块语法，一行声明类型和标题，适合放提示、警告、总结：

[!TIP] 一个建议 备份不是同步，建议至少使用两个不同服务商保存备份。

Inkstone 内置 13 种类型，每种有独立配色，常见类型及可互换的别名如下： | 类型 | 别名（写法可互换） | 典型用途 | | --- | --- | --- | | `[!NOTE]` | — | 普通说明 | | `[!INFO]` / `[!ABSTRACT]` | `summary`、`tldr` | 信息、摘要 | | `[!TIP]` | `hint`、`important` | 技巧、重要提示 | | `[!SUCCESS]` | `check`、`done` | 完成确认 | | `[!WARNING]` | `caution`、`attention` | 注意事项 | | `[!FAILURE]` / `[!DANGER]` | `error`、`bug` | 失败与危险操作 | | `[!QUESTION]` / `[!EXAMPLE]` / `[!QUOTE]` | `help`、`faq`、`cite` | 问答、示例、引用 | 两个实用细节： 1. **可折叠**：标题后加 `-` 默认收起、`+` 默认展开，例如 `> [!NOTE]- 展开看细节` 2. **可嵌套**：在 Callout 里继续写引用块即可嵌套一层，适合"说明中套说明"的场景 类型归一化逻辑见 [renderer.ts#L1041-L1078](https://link.gitcode.com/i/7179cdc0b7277026512d90477c7716c1#L1041-L1078)。 ## 六、技巧 5：行内与块级数学公式 Inkstone 通过 KaTeX 渲染 LaTeX 公式，写法与多数学术笔记软件一致： - **行内公式**：`$E = mc^2$`（注意 `$` 后紧跟内容，不要留空格） - **块级公式**：单独成段，居中显示

$$ \frac{partial f}{partial x} = \sum_{i=1}^{n} \frac{x_i}{i!} $$

只要笔记中出现公式，Inkstone 会自动按需加载 KaTeX 资源（加载器见 [katex-loader.ts](https://link.gitcode.com/i/0010840fc59eb0f7f58b112848ebadc5)），不含公式的笔记零开销。写论文、记推导、做学习笔记都会用到。 ## 七、技巧 6：Mermaid 图表，流程图不用画图软件 把 `mermaid` 作为代码块语言，图表自动渲染：

除 `flowchart` 流程图外，Mermaid 全家桶均可使用：时序图（sequenceDiagram）、类图、甘特图、状态图、饼图……复杂系统架构、工作流程一张图讲清楚，且源码可版本管理、可 diff。 ## 八、技巧 7：标签页组织多方案内容 同一份笔记要放 Windows / macOS / Linux 三种操作方式？用标签页切换，页面更干净：

:::: tabs ::: tab-item Windows 按 Ctrl + Shift + P 打开命令面板 :::

::: tab-item macOS 按 Cmd + Shift + P 打开命令面板 ::: ::::

小技巧：在某个 `::: tab-item` 块内首行写 `:selected:`，可让该标签默认选中。 ## 九、技巧 8：Details 折叠块与技巧 9：代码块增强 **折叠块**适合"高级选项""完整日志"这类可跳过内容：

::: details 点击展开安装日志 npm run build && npm run deploy :::

加 `open` 前缀可默认展开。 **代码块增强**：Inkstone 的代码块支持在围栏语言后附加参数，效果接近文档站点级别的排版：

const name = 'Inkstone' console.log(`Hello, ${name}!`)

- `title="hello.ts"` —— 显示自定义标题 - `line-numbers` —— 显示行号 - `{2}` 或 `hl_lines=2,4-6` —— 高亮指定行 参数解析实现见 [parseFenceInfo](https://link.gitcode.com/i/7179cdc0b7277026512d90477c7716c1#L750-L803)。 ## 十、技巧 10：md-example 活示例与 Front Matter 元信息 **md-example** 是 Inkstone 独有能力：左侧实时渲染效果，右侧同步显示可复制的源码，非常适合在教程类笔记中做"所见即所得"演示，官方欢迎笔记就是用它写成的（内容见 [welcome-notes.ts](https://link.gitcode.com/i/e65ae7f5d3882fb9e997baacfa0d819a) 与 [zh-CN.ts](https://link.gitcode.com/i/e0de6f512b51cf026b8bb3615f4e6609)）。 **Front Matter** 则让笔记自带结构化元信息，预览区会折叠成属性面板，且 `tags` 字段直接计入标签体系：

title: 部署手册 tags: [运维, 自托管] aliases:

• 部署指南

另外三个顺手的小语法值得知道： - `#标签` —— 行内标签，正文随手一写即入库 - `- [ ] 任务` —— 可点击的任务列表，勾选状态会持久保存 - `%% 注释 %%` —— Obsidian 风格注释，预览中不可见，适合留草稿 ## 十一、常见坑与最佳实践 | 问题 | 原因与解决 | | --- | --- | | 行内公式没渲染 | `$` 后紧跟了空格，或中间出现未转义的 `$` | | Callout 不生效 | 类型必须大写且紧跟 `[!`，标题前需要空格；类型写错会降级为默认 NOTE | | 块引用找不到目标 | 块 ID 以 `^` 开头，引用时是 `((id))` 而不是 `((^id))` | | 双链跳错笔记 | 标题匹配忽略空格与大小写，重名笔记建议用 `#章节` 区分 | | 嵌套标签页/折叠块 | 保持开闭标记的冒号数量一致（`::::` 对 `::::`） | 最佳实践：把 WikiLink 用于"笔记间"关系，块引用用于"笔记内"跳转，`![[嵌入]]` 只在内容确实需要复用时使用，避免页面过长。 ## 十二、总结 掌握这 10 个技巧，Inkstone 的 Markdown 扩展基本就用满了： 1. `[[双链]]` 建立笔记网络，不存在即创建 2. `^块ID` + `((块引用))` 实现精确引用 3. `![[ ]]` 嵌入笔记或单个块 4. `[!TYPE]` Callout 快速表达 13 种语气 5. `$...$` / `$$...$$` 写数学公式 6. `mermaid` 代码块画图 7. `:::: tabs` 标签页分方案展示 8. `::: details` 折叠次要内容 9. 代码块支持 `title`、`line-numbers`、行高亮 10. `md-example` 活示例 + Front Matter 元信息 所有笔记导出后仍是标准 `.md` 文本，以上扩展只影响 Inkstone 内的预览效果，换任何 Markdown 编辑器打开都不受影响。动手试试吧：新建一篇笔记，从第一个 `[[双链]]` 开始，你的知识网络就建立起来了。