CheatMD：让 Markdown 笔记变成可执行的交互式命令

vortex52026-06-08 10:15

一、项目概述

CheatMD 是一个用 Go 编写的开源命令行工具，它将普通的 Markdown 文件转化为可交互执行的"速查表"（Cheatsheet）。它的核心哲学极其简洁：你写下的 Markdown 文档，既是给人阅读的笔记，也是给机器执行的命令。

GitHub 仓库：https://github.com/cheatmd-dev/cheatmd

当前版本：v1.0.0-rc.3

许可证：MIT

要求：Go 1.26+

与传统的 navi、tldr、cheat.sh 等工具不同，CheatMD 不引入任何专有格式------你使用的只是最标准的 .md 文件，配合一个 HTML 注释块 <!-- cheat --> 来声明变量和元数据。这意味着你的速查表可以用任何 Markdown 编辑器打开、阅读、分享，同时又能通过 CheatMD 以交互方式运行。

二、核心设计理念

CheatMD 的设计围绕三个核心原则展开：

  1. 纯 Markdown 优先：不创造新语法，利用 Markdown 的标题和代码块作为命令结构，利用 HTML 注释隐藏机器元数据。
  2. 交互式变量注入 ：命令中的变量（如 $container）可以通过 Shell 输出动态生成候选列表，用户通过模糊搜索选择，而非死记硬背参数。
  3. 渐进式复杂度：从最简单的"标题+代码块"开始，按需引入变量、模块、条件分支、链式工作流等高级特性。

#mermaid-svg-lThSjzxazqnrIATn{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-lThSjzxazqnrIATn .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-lThSjzxazqnrIATn .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-lThSjzxazqnrIATn .error-icon{fill:#552222;}#mermaid-svg-lThSjzxazqnrIATn .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-lThSjzxazqnrIATn .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-lThSjzxazqnrIATn .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-lThSjzxazqnrIATn .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-lThSjzxazqnrIATn .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-lThSjzxazqnrIATn .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-lThSjzxazqnrIATn .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-lThSjzxazqnrIATn .marker{fill:#333333;stroke:#333333;}#mermaid-svg-lThSjzxazqnrIATn .marker.cross{stroke:#333333;}#mermaid-svg-lThSjzxazqnrIATn svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-lThSjzxazqnrIATn p{margin:0;}#mermaid-svg-lThSjzxazqnrIATn .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-lThSjzxazqnrIATn .cluster-label text{fill:#333;}#mermaid-svg-lThSjzxazqnrIATn .cluster-label span{color:#333;}#mermaid-svg-lThSjzxazqnrIATn .cluster-label span p{background-color:transparent;}#mermaid-svg-lThSjzxazqnrIATn .label text,#mermaid-svg-lThSjzxazqnrIATn span{fill:#333;color:#333;}#mermaid-svg-lThSjzxazqnrIATn .node rect,#mermaid-svg-lThSjzxazqnrIATn .node circle,#mermaid-svg-lThSjzxazqnrIATn .node ellipse,#mermaid-svg-lThSjzxazqnrIATn .node polygon,#mermaid-svg-lThSjzxazqnrIATn .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-lThSjzxazqnrIATn .rough-node .label text,#mermaid-svg-lThSjzxazqnrIATn .node .label text,#mermaid-svg-lThSjzxazqnrIATn .image-shape .label,#mermaid-svg-lThSjzxazqnrIATn .icon-shape .label{text-anchor:middle;}#mermaid-svg-lThSjzxazqnrIATn .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-lThSjzxazqnrIATn .rough-node .label,#mermaid-svg-lThSjzxazqnrIATn .node .label,#mermaid-svg-lThSjzxazqnrIATn .image-shape .label,#mermaid-svg-lThSjzxazqnrIATn .icon-shape .label{text-align:center;}#mermaid-svg-lThSjzxazqnrIATn .node.clickable{cursor:pointer;}#mermaid-svg-lThSjzxazqnrIATn .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-lThSjzxazqnrIATn .arrowheadPath{fill:#333333;}#mermaid-svg-lThSjzxazqnrIATn .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-lThSjzxazqnrIATn .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-lThSjzxazqnrIATn .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-lThSjzxazqnrIATn .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-lThSjzxazqnrIATn .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-lThSjzxazqnrIATn .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-lThSjzxazqnrIATn .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-lThSjzxazqnrIATn .cluster text{fill:#333;}#mermaid-svg-lThSjzxazqnrIATn .cluster span{color:#333;}#mermaid-svg-lThSjzxazqnrIATn div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-lThSjzxazqnrIATn .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-lThSjzxazqnrIATn rect.text{fill:none;stroke-width:0;}#mermaid-svg-lThSjzxazqnrIATn .icon-shape,#mermaid-svg-lThSjzxazqnrIATn .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-lThSjzxazqnrIATn .icon-shape p,#mermaid-svg-lThSjzxazqnrIATn .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-lThSjzxazqnrIATn .icon-shape .label rect,#mermaid-svg-lThSjzxazqnrIATn .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-lThSjzxazqnrIATn .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-lThSjzxazqnrIATn .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-lThSjzxazqnrIATn :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 生态集成
VS Code / Neovim
Obsidian
Bash/Zsh Widget
tmux / Zellij
输出与执行
print → stdout
copy → 剪贴板
exec → 直接运行
交互层
模糊搜索 (Fuzzy)
变量选择器 (Picker)
历史记录 (Frecency)
Headless JSON-RPC
解析引擎
递归扫描 .md
提取标题/命令/变量
构建索引与标签
语法检查 (Lint)
Markdown 源文件
标题 + 代码块
元数据
目录结构 → 自动标签

三、安装与快速开始

3.1 安装

CheatMD 作为单二进制 Go 程序发布，安装极为简单：

bash 复制代码 
go install github.com/cheatmd-dev/cheatmd/cmd/cheatmd@v1.0.0-rc.3

3.2 初始化

第一次运行建议执行初始化，它会创建配置文件并引导安装 starter packs：

bash 复制代码 
cheatmd init

初始化流程会：

  1. 在 ~/.config/cheatmd/cheatmd.yaml 创建带注释的配置模板
  2. 从远程 registry 拉取可选的 starter cheat packs 清单
  3. 通过交互式选择器让你勾选需要的包（如 git、docker、kubernetes）

3.3 基本使用

bash 复制代码 
cheatmd                    # 浏览当前目录下的 cheats
cheatmd ~/cheats           # 浏览指定 cheats 目录
cheatmd -q "docker"        # 以搜索查询启动
cheatmd --lint ~/cheats    # 检查语法和引用问题
cheatmd packs install      # 安装/更新 cheat packs

四、核心功能详解

4.1 最小可用的 Cheat

一个 CheatMD 可识别的最小单元由两部分组成：Markdown 标题 + 带 title 属性的代码块。

markdown 复制代码 
## Docker: list containers

````sh title:"Show all running containers"
docker ps
````

这就是全部。不需要 <!-- cheat --> 块，不需要变量声明。CheatMD 会把 ## 后面的文字作为可搜索标题，把代码块内容作为命令模板。title:"..." 属性会在选择器中显示为描述文本。

4.2 变量系统：三种声明形式

当命令模板中出现 $name 或 <name> 引用时，CheatMD 会在执行前提示用户输入值。变量在 <!-- cheat --> 注释块中声明，有三种形式：

形式一：仅提示（Prompt-only）
markdown 复制代码 
<!-- cheat
var hostname --- --header "Enter target hostname"
-->

用户会看到一个空白输入框，上方显示 "Enter target hostname"。

形式二：从 Shell 输出获取（=）
markdown 复制代码 
<!-- cheat
var container = docker ps --format "{{.Names}}" --- --header "Select container"
-->

Shell 命令的输出决定交互行为：

  • 0 行输出：回退到手动输入
  • 1 行输出：预填充到输入框，用户可确认或编辑
  • 2+ 行输出：生成分页的可过滤选择列表

这是最强大的特性------你的命令参数可以动态来自当前系统状态。例如 Kubernetes 的 context 和 namespace：

markdown 复制代码 
<!-- cheat
var context   = kubectl config get-contexts -o name --- --header "Context"
var namespace = kubectl --context $context get ns -o name \
    --- --map "cut -d/ -f2" --header "Namespace"
-->

注意 $context 先被解析，其值会注入到 $namespace 的 Shell 命令中。

形式三：字面量（:=）
markdown 复制代码 
<!-- cheat
var user := admin
var url  := https://$host/api/v1
-->

不执行 Shell，直接赋值。:= 右侧的 $other_var 会被同一块中已解析的变量替换。常用于条件分支内的固定值设置。

4.3 选择器选项：控制交互体验

变量声明后可以通过 --- 追加选择器选项，精细控制 Picker 的行为：

选项 作用
--header "..." 选择器顶部显示的标题
--delimiter "X" 按分隔符切分列
--column N 用户看到的第 N 列（仅显示）
--select-column N 选中后返回的第 N 列
--map "cmd" 通过管道 cmd 转换选中值
--multi 允许多选，用空格切换复选框

经典场景：用户看到描述，命令拿到键值

markdown 复制代码 
<!-- cheat
var auth_method = printf 'key\tUse SSH key (default)\npassword\tUse password\n' \
    --- --delimiter '\t' --column 2 --select-column 1 --header "Auth method"
-->

用户看到 "Use SSH key (default)"，但变量实际获得值 key。

--map 做复杂转换

markdown 复制代码 
<!-- cheat
var bucket = aws s3 ls --- --map "awk '{print \$3}'" --header "Bucket"
-->

aws s3 ls 输出带时间戳的行，--map 提取出纯 bucket 名。

4.4 条件分支：动态调整命令

条件块允许根据前面变量的值，决定后续变量如何定义：

markdown 复制代码 
<!-- cheat
var env = printf 'dev\nstaging\nprod\n' --- --header "Environment"

if $env == dev
  var url := https://api.dev.example.com
fi

if $env == staging
  var url := https://api.staging.example.com
fi

if $env == prod
  var url := https://api.example.com
fi
-->

条件只支持 == 和 !=，不支持嵌套。如果变量仅在条件块中定义且无一匹配，该变量会被静默置为空字符串，避免无意义的提示。

4.5 模块系统：复用变量定义

模块通过 export / import 实现跨 Cheat 复用：

在 modules.md 中定义：

markdown 复制代码 
<!-- cheat
export docker_container
var container = docker ps --format "{{.Names}}" --- --header "Container"
-->

在任意 Cheat 中消费：

markdown 复制代码 
## Docker: tail logs

````sh title:"Follow container logs"
docker logs -f $container
````
<!-- cheat
import docker_container
-->

模块支持嵌套导入 ：模块 A 可以 import 模块 B，消费者只需 import A 即可获得全部依赖。模块名在整个 cheats 路径中必须唯一。

4.6 链式工作流（Chains）

链用于将多个 Cheat 组合成有序的多步骤流程，每个步骤是独立的 Cheat：

markdown 复制代码 
## Release: choose version

````sh title:"Show release version"
echo $version
````
<!-- cheat
chain release 1
var version --- --header "Version"
-->

## Release: build

````sh title:"Build release artifact"
make build VERSION=$version
````
<!-- cheat
chain release 2
var version --- --header "Version"
-->

## Release: publish

````sh title:"Publish release artifact"
make publish VERSION=$version
````
<!-- cheat
chain release 3
var version --- --header "Version"
-->

使用时搜索 /chain release，CheatMD 会执行下一个待执行的步骤 然后退出。下次启动时自动恢复进度。完成最后一步后链自动重置。可以通过 cheatmd chain reset [name] 手动重置。
链状态存储 CheatMD 用户 链状态存储 CheatMD 用户 #mermaid-svg-kJY0YEYOipGw4cY2{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-kJY0YEYOipGw4cY2 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-kJY0YEYOipGw4cY2 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-kJY0YEYOipGw4cY2 .error-icon{fill:#552222;}#mermaid-svg-kJY0YEYOipGw4cY2 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-kJY0YEYOipGw4cY2 .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-kJY0YEYOipGw4cY2 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-kJY0YEYOipGw4cY2 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-kJY0YEYOipGw4cY2 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-kJY0YEYOipGw4cY2 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-kJY0YEYOipGw4cY2 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-kJY0YEYOipGw4cY2 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-kJY0YEYOipGw4cY2 .marker.cross{stroke:#333333;}#mermaid-svg-kJY0YEYOipGw4cY2 svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-kJY0YEYOipGw4cY2 p{margin:0;}#mermaid-svg-kJY0YEYOipGw4cY2 .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-kJY0YEYOipGw4cY2 text.actor>tspan{fill:black;stroke:none;}#mermaid-svg-kJY0YEYOipGw4cY2 .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-kJY0YEYOipGw4cY2 .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-svg-kJY0YEYOipGw4cY2 .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#mermaid-svg-kJY0YEYOipGw4cY2 .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#mermaid-svg-kJY0YEYOipGw4cY2 #arrowhead path{fill:#333;stroke:#333;}#mermaid-svg-kJY0YEYOipGw4cY2 .sequenceNumber{fill:white;}#mermaid-svg-kJY0YEYOipGw4cY2 #sequencenumber{fill:#333;}#mermaid-svg-kJY0YEYOipGw4cY2 #crosshead path{fill:#333;stroke:#333;}#mermaid-svg-kJY0YEYOipGw4cY2 .messageText{fill:#333;stroke:none;}#mermaid-svg-kJY0YEYOipGw4cY2 .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-kJY0YEYOipGw4cY2 .labelText,#mermaid-svg-kJY0YEYOipGw4cY2 .labelText>tspan{fill:black;stroke:none;}#mermaid-svg-kJY0YEYOipGw4cY2 .loopText,#mermaid-svg-kJY0YEYOipGw4cY2 .loopText>tspan{fill:black;stroke:none;}#mermaid-svg-kJY0YEYOipGw4cY2 .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-kJY0YEYOipGw4cY2 .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-kJY0YEYOipGw4cY2 .noteText,#mermaid-svg-kJY0YEYOipGw4cY2 .noteText>tspan{fill:black;stroke:none;}#mermaid-svg-kJY0YEYOipGw4cY2 .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-svg-kJY0YEYOipGw4cY2 .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-svg-kJY0YEYOipGw4cY2 .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-svg-kJY0YEYOipGw4cY2 .actorPopupMenu{position:absolute;}#mermaid-svg-kJY0YEYOipGw4cY2 .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-svg-kJY0YEYOipGw4cY2 .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-kJY0YEYOipGw4cY2 .actor-man circle,#mermaid-svg-kJY0YEYOipGw4cY2 line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-svg-kJY0YEYOipGw4cY2 :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 用户继续其他操作... cheatmd -q "/chain release" 读取当前步骤 (step 1) 提示输入 version version = 1.2.0 执行 echo 1.2.0，退出 cheatmd -q "/chain release" 读取当前步骤 (step 2) 提示输入 version version = 1.2.0 执行 make build VERSION=1.2.0，退出 cheatmd -q "/chain release" 读取当前步骤 (step 3) 执行 make publish... 重置链到 step 1

五、配置与个性化

配置文件位于 ~/.config/cheatmd/cheatmd.yaml，所有设置均为可选：

yaml 复制代码 
# 默认 cheats 路径
path: ~/cheats

# 最终命令的处理方式: print / copy / exec
output: print

# 运行变量命令和执行时使用的 shell
shell: /bin/bash

# 变量引用语法: dollar ($name) / angle (<name>) / both
var_syntax: dollar

# 是否将未声明的变量引用也作为提示
allow_undeclared_vars: false

# 快捷键绑定
key_substitute: "ctrl+t"   # 环境变量+历史替换搜索
key_preview: "ctrl+y"      # Markdown 预览
key_history: "ctrl+h"      # 执行历史
key_open: "ctrl+o"         # 打开源文件
key_widget: "\C-g"        # Shell widget 触发键

Substitute 搜索（Ctrl+T） 是一个非常实用的功能：在变量提示界面按 Ctrl+T，会弹出一个模糊搜索框，覆盖当前所有环境变量以及 Shell 历史中的变量赋值（如 VAR=value、export VAR=value）。选中即可填充到当前提示。

执行历史 保存在 ~/.local/share/cheatmd/history.jsonl，记录每次运行的最终命令、变量值和 Cheat 来源。主选择器使用 Frecency 算法排序------你最近频繁使用的 Cheat 会浮到顶部。

六、生态系统集成

CheatMD 的强大之处不仅在于独立的 TUI，还在于它与整个开发工具链的深度集成。

6.1 Shell 集成

Bash / Zsh Widget

将 CheatMD 嵌入 readline，选中命令后直接插入当前命令行：

bash 复制代码 
# ~/.bashrc
eval "$(cheatmd widget bash)"

# ~/.zshrc
eval "$(cheatmd widget zsh)"

默认按 Ctrl+G 触发，选中命令后落在你当前的 Shell 提示符上，按 Enter 即可执行。

tmux

bash 复制代码 
# ~/.tmux.conf
bind-key -n C-n split-window "$SHELL --login -i -c 'cheatmd --print | tr -d \"\\r\\n\" | tmux load-buffer -b tmp - ; tmux paste-buffer -t {last} -b tmp -d'"

按 Ctrl+N 在分屏中打开 CheatMD，结果粘贴回原 pane。

Zellij

bash 复制代码 
bind "Ctrl n" {
    Run "sh" "-c" "content=$(cheatmd --print); zellij action toggle-floating-panes; zellij action write-chars \"$content\"" {
        floating true
        close_on_exit true
    };
}

在浮动 pane 中打开，结果直接输入到原 pane。

6.2 编辑器扩展

编辑器 功能
VS Code 语法高亮、诊断、自动补全、CodeLens 执行按钮
Neovim 语法高亮、异步诊断、补全、:CheatMDRun 命令
Obsidian 内联运行按钮、lint 状态、执行结果展示、变量自动补全

6.3 Headless 模式（JSON-RPC）

这是编辑器插件的底层协议。启动时加上 --headless 和精确查询：

bash 复制代码 
cheatmd --headless -q "docker exec container"

CheatMD 通过 stdout/stdin 以 JSON-RPC 2.0 通信：

  • 需要用户输入时，发送 prompt 请求（含变量名、选项列表等）
  • 宿主应用（如编辑器）展示 UI 后，通过 result 响应返回值
  • 执行完成后发送 completed 通知（含最终命令、输出、退出码）

这使得 CheatMD 的核心引擎可以被任何支持 JSON-RPC 的客户端调用，无需绑定特定的 TUI 实现。

七、数据迁移：从其他工具导入

CheatMD 内置 convert 子命令，支持从主流速查表工具无痛迁移：

bash 复制代码 
# 从 navi 导入
cheatmd convert navi ~/navi-cheats -o ~/cheats

# 从 tldr-pages 导入
cheatmd convert tldr ~/tldr/pages/common/tar.md -o ~/cheats/tar.md

# 从 cheat/cheatsheets 导入
cheatmd convert cheat ~/cheat/cheatsheets -o ~/cheats

转换器会尽量保留原有结构，将 navi 的 <name> 变量转为 CheatMD 的 $name，将 tldr 的 {``{placeholder}} 转为带默认值的变量提示，将 cheat 的注释转为 title 描述。

八、与同类工具的对比

#mermaid-svg-sQ7kR8NpjzY2cOmU{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-sQ7kR8NpjzY2cOmU .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-sQ7kR8NpjzY2cOmU .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-sQ7kR8NpjzY2cOmU .error-icon{fill:#552222;}#mermaid-svg-sQ7kR8NpjzY2cOmU .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-sQ7kR8NpjzY2cOmU .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-sQ7kR8NpjzY2cOmU .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-sQ7kR8NpjzY2cOmU .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-sQ7kR8NpjzY2cOmU .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-sQ7kR8NpjzY2cOmU .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-sQ7kR8NpjzY2cOmU .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-sQ7kR8NpjzY2cOmU .marker{fill:#333333;stroke:#333333;}#mermaid-svg-sQ7kR8NpjzY2cOmU .marker.cross{stroke:#333333;}#mermaid-svg-sQ7kR8NpjzY2cOmU svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-sQ7kR8NpjzY2cOmU p{margin:0;}#mermaid-svg-sQ7kR8NpjzY2cOmU .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-sQ7kR8NpjzY2cOmU .cluster-label text{fill:#333;}#mermaid-svg-sQ7kR8NpjzY2cOmU .cluster-label span{color:#333;}#mermaid-svg-sQ7kR8NpjzY2cOmU .cluster-label span p{background-color:transparent;}#mermaid-svg-sQ7kR8NpjzY2cOmU .label text,#mermaid-svg-sQ7kR8NpjzY2cOmU span{fill:#333;color:#333;}#mermaid-svg-sQ7kR8NpjzY2cOmU .node rect,#mermaid-svg-sQ7kR8NpjzY2cOmU .node circle,#mermaid-svg-sQ7kR8NpjzY2cOmU .node ellipse,#mermaid-svg-sQ7kR8NpjzY2cOmU .node polygon,#mermaid-svg-sQ7kR8NpjzY2cOmU .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-sQ7kR8NpjzY2cOmU .rough-node .label text,#mermaid-svg-sQ7kR8NpjzY2cOmU .node .label text,#mermaid-svg-sQ7kR8NpjzY2cOmU .image-shape .label,#mermaid-svg-sQ7kR8NpjzY2cOmU .icon-shape .label{text-anchor:middle;}#mermaid-svg-sQ7kR8NpjzY2cOmU .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-sQ7kR8NpjzY2cOmU .rough-node .label,#mermaid-svg-sQ7kR8NpjzY2cOmU .node .label,#mermaid-svg-sQ7kR8NpjzY2cOmU .image-shape .label,#mermaid-svg-sQ7kR8NpjzY2cOmU .icon-shape .label{text-align:center;}#mermaid-svg-sQ7kR8NpjzY2cOmU .node.clickable{cursor:pointer;}#mermaid-svg-sQ7kR8NpjzY2cOmU .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-sQ7kR8NpjzY2cOmU .arrowheadPath{fill:#333333;}#mermaid-svg-sQ7kR8NpjzY2cOmU .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-sQ7kR8NpjzY2cOmU .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-sQ7kR8NpjzY2cOmU .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-sQ7kR8NpjzY2cOmU .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-sQ7kR8NpjzY2cOmU .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-sQ7kR8NpjzY2cOmU .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-sQ7kR8NpjzY2cOmU .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-sQ7kR8NpjzY2cOmU .cluster text{fill:#333;}#mermaid-svg-sQ7kR8NpjzY2cOmU .cluster span{color:#333;}#mermaid-svg-sQ7kR8NpjzY2cOmU div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-sQ7kR8NpjzY2cOmU .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-sQ7kR8NpjzY2cOmU rect.text{fill:none;stroke-width:0;}#mermaid-svg-sQ7kR8NpjzY2cOmU .icon-shape,#mermaid-svg-sQ7kR8NpjzY2cOmU .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-sQ7kR8NpjzY2cOmU .icon-shape p,#mermaid-svg-sQ7kR8NpjzY2cOmU .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-sQ7kR8NpjzY2cOmU .icon-shape .label rect,#mermaid-svg-sQ7kR8NpjzY2cOmU .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-sQ7kR8NpjzY2cOmU .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-sQ7kR8NpjzY2cOmU .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-sQ7kR8NpjzY2cOmU :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} CheatMD优势
传统工具
navi
tldr
cheat.sh
pet
纯 Markdown

无专有格式
Shell 动态变量

实时系统状态
模块+链式

可复用可编排
Headless JSON-RPC

编辑器原生集成
模糊搜索+历史

Frecency 排序

特性 CheatMD navi tldr cheat.sh
文件格式 纯 Markdown .cheat 专有格式 特定 Markdown 纯文本
变量交互 Shell 输出驱动 Picker 支持变量 静态占位符 静态占位符
模块复用 import/export @extends 无 无
链式工作流 原生支持 无 无 无
条件分支 if/fi 有限 无 无
Shell 集成 Widget + tmux + Zellij Widget 无 无
编辑器支持 VS Code + Neovim + Obsidian 有限 插件 无
Headless API JSON-RPC 无 无 无
数据迁移 内置 convert 无 无 无

九、总结

CheatMD 代表了一种"文档即代码"的极端优雅实现：它不要求你学习新格式，不强迫你维护两套资料（给人看的和给机器用的），而是让同一套 Markdown 笔记同时服务于两种场景。

对于运维工程师、DevOps、SRE、以及任何需要频繁操作命令行的开发者来说，CheatMD 的价值在于降低认知负荷 ------你不需要记住 docker exec 后面跟哪个容器 ID，不需要记住 kubectl 的当前 context，不需要记住 SSH 的特定端口。这些动态信息由 Shell 实时提供，你只需做选择。

随着 VS Code、Neovim、Obsidian 插件的成熟，以及 Headless JSON-RPC 模式的开放，CheatMD 正在从一个命令行工具进化为一个可嵌入任何工作流的命令编排引擎 。如果你已经在用 Markdown 记录命令笔记，给它加上 <!-- cheat --> 注释，就是通往交互式执行世界的全部代价。

相关推荐
じ☆冷颜〃1 小时前
Picard–Lindelöf定理在CS中的应用：理论框架与算法基础
人工智能·经验分享·笔记·算法·机器学习
LuminousCPP1 小时前
C 语言系列终章｜编译与链接 + 预处理
c语言·经验分享·笔记·预处理·编译链接
.千余1 小时前
【C++】 String 常用操作：增删查改 | 查找 | 截取 | IO
java·服务器·开发语言·c++·笔记·学习
xian_wwq1 小时前
【学习笔记】「大模型安全：攻击面演化史」第 04 篇-模型窃取与供应链安全
笔记·学习·ai安全
十月的皮皮1 小时前
C语言学习笔记20260607-判断一个数是否为2的n次方（三种方法）
c语言·笔记·学习
sheeta19981 小时前
LeetCode 补拙笔记 日期：2026.06.07 题目：49. 字母异位词分组
笔记·算法·leetcode
问心无愧05132 小时前
ctf show web入门101
android·前端·笔记
AOwhisky2 小时前
MySQL 学习笔记（第五期）：用户管理与权限控制
linux·运维·数据库·笔记·学习·mysql
ouliten2 小时前
C++笔记：偏现代C++日志系统
c++·笔记
热门推荐
01【AI】2026 年具身智能模型和世界模型总结022026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf03GitHub 镜像站点04Codex 下载安装指南：Windows 和 macOS 官方版下载05Codex 桌面端更新后 Chrome 插件和 Computer Use 不可用，怎么排查和修复06【踩坑记录 | 第一篇】微软商店无法使用时，如何手动安装 OpenAI Codex？附`.msix`文件系统错误解决方法07CC-Switch & Claude 基于 Linux 服务器安装使用指南08CC-Switch 下载、安装与使用配置指南【2026.5.29】092026 AI 编程工具终极实战指南：Cursor vs Claude Code vs Copilot，开发者该怎么选？10AI科技热点日报 | 2026年6月1日