stepchowfun/mull 来源: https://github.com/stepchowfun/mull

Mull 📖

构建状态 (https://github.com/stepchowfun/mull/actions?query=branch%3Amain)

Mull 是一个用于管理存储在纯文本文件中的 wiki 的工具。它提供了 Visual Studio Code (https://code.visualstudio.com/) / Cursor (https://cursor.com/) 扩展，支持语法高亮、悬停预览、自动补全、诊断、格式化、重构等功能。

欢迎使用 Mull。

快速导览

页面与链接

Wiki 是一个扩展名为 .mull 的文本文件。它包含相互链接的页面，所有内容都在同一个文件中。下面是一个包含 3 个页面的简单 wiki：

``md

Home

我的首选早餐是 [Pancakes]，配上新鲜的 [Lemons]。

Lemons

搭配 [Pancakes] 效果极佳。

Pancakes

• 1 杯面粉
• 1 杯牛奶
• 1 个鸡蛋
• 挤入一些 [Lemons] ``

每个页面以 # 标题 开头，后面跟着页面内容。要链接到某个页面，使用方括号，例如 [Lemons]。当你输入左括号 [ 时，自动补全会启动，帮助你找到所需的页面。

自动补全。

每个 wiki 都从 Home 页面开始。Mull 要求从 Home 出发，通过跟随链接，每个其他页面都是可达的（直接或间接）。这一规则促进了一种不依赖层级结构的基本组织方式。页面同时承担了传统上由文件和目录扮演的角色。

当你保存文件时（默认），或者你显式请求时，Mull 会格式化 wiki。它根据页面之间的链接来决定文件中页面的顺序，因此你无需操心。链接到页面是组织它们的唯一方式。

链接到文件和目录

你可以链接到照片、电子表格等任何文件。Mull 会检查被链接的文件是否确实存在，并且你可以不离开编辑器直接预览它们。

文件预览。

文件放在与 wiki 同级的目录中，该目录以 wiki 的名称命名，将 .mull 扩展名替换为 _files。例如，如果 wiki 是 my_wiki.mull，文件放在 my_wiki_files 中。如果你有一个文件叫 my_wiki_files/photos/beach.jpg，可以用 [/photos/beach.jpg] 来链接它。你也可以链接到目录，如 [/photos/]。自动补全会在你链接文件和目录时帮助你输入名称。

你还可以按住 Shift 键拖放或直接粘贴文件到编辑器中。

正如每个页面都必须从 Home 可达一样，_files 中的每个文件（如果存在）也必须从 wiki 中被链接到。链接到一个目录隐式地算作链接到其中的所有内容。空目录需要单独的链接。

打开通往其他页面的门户

门户（portal）是通往另一个页面的窗口。它保存该页面内容的副本，Mull 会保持它们同步。例如，如果你有一个叫 Pancakes 的页面，你可以从另一个页面这样打开一个门户：

``md 这是我最喜欢的早餐：

::: [Pancakes] ::: ``

当 wiki 被格式化时（例如，在保存时），那一行会被展开为页面的副本：

``md 这是我最喜欢的早餐：

::: [Pancakes]

• 1 杯面粉
• 1 杯牛奶
• 1 个鸡蛋
• 挤入一些 [Lemons] ::: ``

你可以编辑页面或它的任何一个门户，格式化会将你的编辑传播到其余部分。

用脚本扩展 Mull

假设你有一个想要保持排序的列表：

``md 我的储藏室里的东西：

• 大蒜
• 犹太盐
• 味噌
• 橄榄油
• 大米 ``

Mull 可以帮你做到这一点；你只需要教它如何排序。创建一个名为 _files/scripts/sort.sh 的文件，内容如下：

sh #!/bin/sh sort "$@"

用 chmod +x _files/scripts/sort.sh 使其可执行。现在你可以把列表放在一个 sort 块中：

``md 我的储藏室里的东西：

::: sort

• 大蒜
• 犹太盐
• 味噌
• 橄榄油
• 大米 ::: ``

之后每次 wiki 被格式化时（例如，在保存时），Mull 会自动对该列表排序。该排序脚本接受参数，所以你可以例如用 ::: sort -r 进行反向排序。

在块中使用脚本就算链接到了它，因此它不需要像 _files 中的其他文件那样被 wiki 链接到。未使用的脚本仍然需要在 wiki 中的某处添加链接（例如 [/scripts/sort.sh]）。

转义与代码

要将 [ 或 ] 等特殊符号按字面使用，在前面加一个反斜杠，如 \[。你也可以像 Markdown 中一样使用反引号表示逐字文本，如 `this`。

也支持围栏代码块，并对常见语言提供语法高亮。

``md

Home

我正在学习 Python，目前在做一个 [Dice game]。

Dice game

``python import random

for turn in range(3): roll = random.randint(1, 6) print(f“Roll {turn + 1}: {roll}“)

print(“Thanks for playing!”)

``

在页面标题或代码中不需要转义。

## 键盘快捷键

以下常用键盘快捷键在浏览和编辑 wiki 时非常有用：

| 操作 | macOS | Windows |
| --- | --- | --- |
| 从链接跳转到页面 | `F12` 或 `Command + 点击` | `F12` 或 `Control + 点击` |
| 跳转到链接到某页面的链接（即反向链接） | `Shift + F12` | `Shift + F12` |
| 跳回到之前访问的页面 | `Command + [` | `Alt + Left` |
| 向前跳转到下一个访问的页面 | `Command + ]` | `Alt + Right` |
| 跳转到当前页面的开头 | `Command + Up` | `Control + Home` |
| 跳转到当前页面的末尾 | `Command + Down` | `Control + End` |
| 跳转到下一个错误 | `F8` | `F8` |
| 跳转到上一个错误 | `Shift + F8` | `Shift + F8` |
| 查找页面 | `Command + Shift + O` | `Control + Shift + O` |
| 代码操作（例如，创建缺失的页面） | `Command + .` | `Control + .` |
| 重命名页面 | `F2` | `F2` |
| 格式化 wiki | `Shift + Option + F` | `Shift + Alt + F` |

这些键盘快捷键大多数是 Visual Studio Code 和 Cursor 中的标准快捷键，你可能已经熟悉了。你可以重新映射它们。

## 使用方法

在 Visual Studio Code 或 Cursor 中[安装](#安装说明) Mull 后，你可以在编辑器中打开一个 `.mull` 文件来运行它。

你也可以在命令行中运行 Mull（例如，在 CI 任务中），如下所示：

``sh
mull check --path wiki.mull
``

以下是支持的命令行选项：

用法: mull [命令]

命令: check 检查 wiki 是否有效且已格式化，并运行其脚本 format 格式化 wiki，运行其脚本（默认） page 打印 wiki 中某个页面的内容 language-server 启动语言服务器（编辑器使用此功能） help 打印此消息或给定子命令的帮助

选项: -v, –version 打印版本 -h, –help 打印帮助 ``

安装说明

要使用 Mull，你必须安装二进制文件，并可选地安装 Visual Studio Code / Cursor 扩展。二进制文件负责所有工作，可以在命令行中独立使用。IDE 扩展使用二进制文件来提供丰富的 wiki 编辑体验。

在 macOS 或 Linux (AArch64 或 x86-64) 上安装

如果你运行的是 macOS 或 Linux (AArch64 或 x86-64)，可以用以下命令安装 Mull：

sh curl https://raw.githubusercontent.com/stepchowfun/mull/main/install.sh -LSfs | sh

它会先安装二进制文件，然后为 Visual Studio Code 和/或 Cursor 安装扩展。可以再次使用相同的命令更新到最新版本。

安装脚本支持以下可选环境变量：

• VERSION=x.y.z（默认为最新版本）
• PREFIX=/path/to/install（默认为 /usr/local/bin）

例如，以下命令会将二进制文件安装到当前工作目录：

sh curl https://raw.githubusercontent.com/stepchowfun/mull/main/install.sh -LSfs | PREFIX=. sh

请注意，如果你更改了安装路径，可能还需要相应地在 Visual Studio Code 或 Cursor 中更改 mull.executablePath。

如果你不倾向于使用这种安装方式，可以从最新发布版本 (https://github.com/stepchowfun/mull/releases/latest) 下载二进制文件，使其可执行（例如用 chmod），然后将其放入 PATH (https://en.wikipedia.org/wiki/PATH_(variable)) 中的某个目录（例如 /usr/local/bin）。然后你可以按照下面的说明安装 Visual Studio Code / Cursor 扩展。

在 Windows (AArch64 或 x86-64) 上安装二进制文件

如果你运行的是 Windows (AArch64 或 x86-64)，从最新发布版本 (https://github.com/stepchowfun/mull/releases/latest) 下载二进制文件，并将其重命名为 mull（如果启用了文件扩展名显示则为 mull.exe）。在你的 %PROGRAMFILES% 目录中创建一个名为 Mull 的目录（例如 C:\Program Files\Mull），并将重命名后的二进制文件放入其中。然后，在控制面板的“系统属性“的“高级“选项卡中，点击“环境变量…“，在“系统变量“下的 PATH 变量中添加新的 Mull 目录的完整路径。

请注意，如果 Windows 配置为非英语语言，Program Files 目录可能有不同的名称。

要更新现有安装，只需替换现有的二进制文件即可。

使用 Cargo 安装二进制文件

如果你有 Cargo (https://doc.rust-lang.org/cargo/)，可以按照以下方式安装 Mull：

sh cargo install mull

你可以使用 --force 参数来更新现有安装。

安装 Visual Studio Code / Cursor 扩展

首先，确保你已安装 Visual Studio Code (https://code.visualstudio.com/) 或 Cursor (https://cursor.com/)。

要安装 Mull 扩展，从最新发布版本 (https://github.com/stepchowfun/mull/releases/latest) 下载 mull.vsix 文件，然后通过主侧边栏中“扩展“视图顶部 ... 菜单中的“从 VSIX 安装…“选项进行安装。

请注意，macOS / Linux 安装命令会自动安装扩展，所以如果你使用那种安装方式，可以跳过本节。

要更新现有安装，只需重新安装即可。