Mull: note-taking with a language server / vscode extension
本文为原文前 6,000 字符的节选翻译，完整内容请查看原文。
Mull 📖 Mull is a tool for managing a wiki stored in a plain text file. It has a Visual Studio Code / Cursor extension which provides syntax highlighting, hover previews, completions, diagnostics, formatting, refactoring, etc.
Mull 📖 Mull 是一个用于管理存储在纯文本文件中维基（wiki）的工具。它拥有一个 Visual Studio Code / Cursor 扩展，提供语法高亮、悬停预览、自动补全、诊断、格式化、重构等功能。
A quick tour Pages and links A wiki is a text file with a .mull extension. It contains pages which link to each other, all in the same file. Here’s a little wiki with 3 pages: # Home My go-to breakfast is [Pancakes] with fresh [Lemons]. # Lemons Great on [Pancakes]. # Pancakes - 1 cup of flour - 1 cup of milk - 1 egg - A squeeze of [Lemons] Each page starts with a # Title, followed by the contents of the page. To link to a page, use square brackets like [Lemons]. When you type the opening [, autocomplete kicks in to help you find the page you’re looking for.
快速导览 页面与链接 维基是一个扩展名为 .mull 的文本文件。它包含相互链接的页面，且所有内容都在同一个文件中。这是一个包含 3 个页面的小型维基示例：# Home 我的早餐首选是 [Pancakes] 配新鲜的 [Lemons]。# Lemons 配 [Pancakes] 很棒。# Pancakes - 1 杯面粉 - 1 杯牛奶 - 1 个鸡蛋 - 挤一点 [Lemons] 每个页面都以 # 标题开头，后跟页面内容。要链接到某个页面，请使用方括号，例如 [Lemons]。当你输入左方括号 [ 时，自动补全功能会启动，帮助你找到所需的页面。
Every wiki starts with a Home page. Mull requires that every other page is reachable (directly or indirectly) by following links, starting from Home. This rule promotes a basic form of organization that doesn’t involve any hierarchical structure. Pages serve the roles traditionally filled by files and directories. Mull formats the wiki when you save the file (default), or when you explicitly request it. It chooses the ordering of the pages in the file based on the links between them, so you don’t have to think about it. Linking to pages is the only way to organize them.
每个维基都以 Home 页面开始。Mull 要求从 Home 开始，通过链接（直接或间接）可以访问到其他所有页面。这一规则促进了一种不涉及任何层级结构的基本组织形式。页面承担了传统上由文件和目录扮演的角色。Mull 会在保存文件时（默认）或当你明确请求时格式化维基。它会根据页面间的链接关系自动选择页面在文件中的排序，因此你无需为此操心。链接页面是组织它们的唯一方式。
Linking to files and directories You can link to files like photos, spreadsheets, or anything else. Mull checks that the linked files actually exist, and you can preview them without leaving the editor. Files go in a directory next to the wiki named after the wiki, with the .mull extension replaced with _files. For example, if the wiki is my_wiki.mull, the files go in my_wiki_files. If you have a file called my_wiki_files/photos/beach.jpg, you can link it with [/photos/beach.jpg]. You can also link to directories like [/photos/]. Autocomplete helps you enter the names of files and directories when linking to them. You can also drag-and-drop (while holding the Shift key) or paste files directly into the editor. Just as every page must be reachable from Home, every file in
链接到文件和目录 你可以链接到照片、电子表格或其他任何文件。Mull 会检查链接的文件是否存在，并且你无需离开编辑器即可预览它们。文件存放在维基旁的一个目录中，该目录以维基命名，并将 .mull 扩展名替换为 _files。例如，如果维基是 my_wiki.mull，文件则存放在 my_wiki_files 中。如果你有一个名为 my_wiki_files/photos/beach.jpg 的文件，你可以通过 [/photos/beach.jpg] 进行链接。你也可以链接到目录，例如 [/photos/]。自动补全功能可以帮助你在链接时输入文件和目录名称。你还可以通过拖放（按住 Shift 键）或直接粘贴文件到编辑器中。正如每个页面都必须能从 Home 访问到一样，
Opening a portal to another page A portal is a window into another page. It holds a copy of the page’s contents, and Mull keeps them in sync. For example, if you have a page called Pancakes, you can open a portal to it from another page like this: This is my favorite breakfast: ::: [Pancakes] ::: When the wiki is formatted (e.g., on save), that line will be expanded into a copy of the page: This is my favorite breakfast: ::: [Pancakes] - 1 cup of flour - 1 cup of milk - 1 egg - A squeeze of [Lemons] ::: You can edit the page or any of its portals, and formatting will propagate your edits to the rest.
打开通往另一个页面的门户 门户是通往另一个页面的窗口。它保存了页面内容的副本，Mull 会保持它们同步。例如，如果你有一个名为 Pancakes 的页面，你可以从另一个页面打开通往它的门户，如下所示：这是我最喜欢的早餐：::: [Pancakes] ::: 当维基被格式化（例如在保存时），该行将展开为页面的副本：这是我最喜欢的早餐：::: [Pancakes] - 1 杯面粉 - 1 杯牛奶 - 1 个鸡蛋 - 挤一点 [Lemons] ::: 你可以编辑页面或其任何门户，格式化操作会将你的编辑同步到其余部分。
Extending Mull with scripts Suppose you have a list that you want to keep sorted: The contents of my pantry: - Garlic - Kosher salt - Miso - Olive oil - Rice Mull can help with this; you just have to teach it about sorting. Create a file called
使用脚本扩展 Mull 假设你有一个想要保持排序的列表：我的食品储藏室内容：- 大蒜 - 犹太盐 - 味噌 - 橄榄油 - 大米 Mull 可以帮助你实现这一点；你只需要教它如何排序。创建一个名为
Escaping and code To use a special symbol like [ or ] literally, put a backslash before it, like [. You can also use backticks to denote verbatim text like this, as in Markdown. Fenced code blocks are supported too, with syntax highlighting for common languages. # Home I’m learning Python, currently working on a [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!") No escaping is necessary inside page titles or code.
转义与代码 要按字面意思使用 [ 或 ] 等特殊符号，请在其前面加上反斜杠，例如 [。你也可以像在 Markdown 中一样使用反引号来表示原样文本，例如 this。同时也支持围栏代码块，并为常见语言提供语法高亮。# 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!") 在页面标题或代码内部无需转义。
Keyboard shortcuts These common keyboard shortcuts are helpful when navigating and editing a wiki: Action macOS Windows Jump to a page from a link F12 or Command + click F12 or Control + click Jump to links to a page (i.e., backlinks) Shift + F12 Shift + F12 Jump back to the previously visited page Command + [ Alt + Left Jump forward to the next visited page Command + ] Alt + Right Jump to the start of the current page Command + Up Control + Home Jump to the end of the current page Command + Down Control + End Jump to the next error F8 F8 Jump to the previous error Shift + F8 Shift + F8 Find a page Command + Shift + O Control + Shift + O Code actions (e.g., create a missing page) Command + . Control + . Rename a page F2 F2 Format the wiki Shift + Option + F Shift + Alt + F Most of these keyboard shortcuts are standard in Visual Studio Code and Cursor, so they may be familiar to you already. You can remap them.
键盘快捷键 这些常见的键盘快捷键在导航和编辑维基时非常有用：操作 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 格式化维基 Shift + Option + F Shift + Alt + F 大多数这些键盘快捷键在 Visual Studio Code 和 Cursor 中是标准的，因此你可能已经很熟悉了。你可以重新映射它们。
Usage Once Mull is installed for Visual Studio Code or Cursor, you can run it by opening a .mull file in the editor. You can also run Mull from the command line (e.g., in a CI job) as follows: mull check —path wiki.mull Here are the supported command-line options: Usage: mull [COMMAND] Commands: check Check that a wiki is valid and formatted, with its scripts run format Format a wiki, running its scripts (default) page Print the content of a page in a wiki language-server Start the language server (editors use this) help Print this message or the help of the given subcommand(s) Options: -v, —version Print version -h, —help Print help Installation instructio
用法 一旦为 Visual Studio Code 或 Cursor 安装了 Mull，你就可以通过在编辑器中打开 .mull 文件来运行它。你也可以从命令行（例如在 CI 作业中）运行 Mull，如下所示：mull check —path wiki.mull 以下是支持的命令行选项：用法：mull [COMMAND] 命令：check 检查维基是否有效且已格式化，并运行其脚本 format 格式化维基，运行其脚本（默认） page 打印维基中页面的内容 language-server 启动语言服务器（编辑器使用此功能） help 打印此消息或给定子命令的帮助 选项：-v, —version 打印版本 -h, —help 打印帮助 安装说明