Shoin 终端 Markdown 编辑器详细部署教程

Shoin 是一款极简的终端 Markdown 编辑器，它将“无干扰写作”理念发挥到极致。它没有菜单栏、文件树或标签页，只有一个居中的文本列，提供即时且诚实的 Markdown 预览，并完全支持 Vim 风格的模态编辑和 Obsidian 风格的双链笔记功能。

📋 目录

Shoin 是什么
安装前准备
安装 Shoin
- 从源码仓库安装
- 从本地克隆安装
- 快速尝试
初始化配置
快速入门
核心功能与使用
- Vim 模态编辑与移动
- Writer 格式化动词
- 面板与导航
- 写作模式
- 笔记组合与链接
- 图片嵌入
- 命令行导出
配置详解
更新与卸载
常见问题排查

Shoin 是什么

Shoin（書院）得名于传统日式房屋中靠窗的书斋角落。它继承了这种“空无一物，唯有书桌”的精神，将编辑器界面精简到极致。

核心理念：

无永久界面：所有面板（文件树、模糊查找器等）都是按键召唤，用完即走。
诚实的实时预览：光标所在行显示原始 Markdown 源码，其他行渲染为最终效果，所见即所得，永无偏差。
Vim 模态编辑：完全支持 Normal/Insert/Visual 模式、操作符、文本对象、寄存器、宏重复等。
笔记组合：支持 [[note]] 链接和 ![[note]] 嵌入，完美兼容 Obsidian 语法，可导出为 Markdown、HTML 或 PDF。
纯文本配置：使用 TOML 格式，修改后热加载生效。

安装前准备

系统要求

Rust 工具链：版本 1.88 或更新。
终端：需支持 真彩色 (24-bit)（大多数现代终端如 iTerm2、Windows Terminal、GNOME Terminal 均支持）。
字体（可选但推荐）：安装 Nerd Font 补丁字体（如 JetBrainsMono Nerd Font）以获得最佳图标显示效果。如不使用，可在配置中设置 glyphs.nerd_fonts = false。
PDF 导出（可选）：需要安装 pandoc 和 typst（macOS 可用 brew install pandoc typst）。

安装 Rust（如未安装）

1
2
3

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
rustc --version  # 确认版本 >= 1.88

安装 Shoin

从源码仓库安装（推荐）

使用 Cargo 直接从 Git 仓库安装：

1	cargo install --git https://github.com/nol00p/shoin

此命令会将 shoin 二进制文件安装到 ~/.cargo/bin 目录。请确保该目录已添加到您的 PATH 环境变量中。

从本地克隆安装（用于开发或自定义）

1
2
3

git clone https://github.com/nol00p/shoin
cd shoin
cargo install --path .

快速尝试（不安装）

在克隆的仓库目录中，可直接运行：

1	cargo run -- notes.md

这会在不全局安装的情况下启动 Shoin 并打开 notes.md 文件。

初始化配置

Shoin 在首次启动时不会自动创建配置文件。您需要手动执行初始化命令：

1	shoin --init-config

此命令会在 ~/.config/shoin/ 目录下生成带有详细注释的默认配置文件 (*.conf)。如果该目录已存在配置文件，此命令不会覆盖它们，可使用 --force 强制覆盖：

1	shoin --init-config --force

快速入门

启动 Shoin：

bash

1 2	shoin my_note.md # 打开一个已有或新建文件（:w 时创建） shoin # 启动空白页面，会显示一个“盆景”和五个入口

基本操作流程：
- 按 i 进入 插入 (Insert) 模式 开始输入文字。
- 按 Esc 键返回 普通 (Normal) 模式。
- 输入 :w 并回车，保存文件。
- 输入 :q 并回车，退出编辑器。
获取帮助：
在 Shoin 中，输入 :help 并回车，即可在编辑器内打开详细的帮助文档。可以进一步查看 :help bindings、:help commands、:help writer 和 :help config。

核心功能与使用

Vim 模态编辑与移动

Shoin 实现了纯正的 Vim 键位，支持操作符、文本对象和计数。

分类	键位	功能
移动	`h/j/k/l` 或方向键	左/下/上/右移动
	`w/b/e`	按单词移动（下一个/上一个/词尾）
	`0` / `^` / `$`	行首/行首非空白/行尾
	`gg` / `G`	文件首/文件尾
编辑	`i` / `a`	在光标前/后插入
	`o` / `O`	在下方/上方新开一行
	`x`	删除当前字符
	`dd` / `yy` / `p`	删除/复制/粘贴行
	`u` / `Ctrl-r`	撤销/重做
	`.`	重复上次修改
搜索	`/` `?` `n` `N`	前向/后向搜索，下一个/上一个匹配
命令	`:`	进入命令行模式（如 `:w`, `:q`）

操作符示例：d2w（删除两个单词）、ciw（修改当前单词）、ya(（复制括号内所有内容）、>ip（缩进整个段落）。

Writer 格式化动词

在普通或可视模式下，使用 g 前缀快速格式化文本。

键位	功能
`gb`	加粗 `bold`
`gi`	斜体 `italic`
`gt`	切换任务复选框 `- [ ]` ↔ `- [x]`
`gl`	创建链接 `[text](url)`，光标自动定位到 URL 处
`gh`	高亮 `==highlight==`
`g1`-`g6`	设置为 1-6 级标题
`g0`	移除标题标记
`gk`	行内代码 `code`
`gp`	开始新段落
`gf`	跟随光标下的链接（若目标不存在则创建）
`gx`	用桌面应用打开链接或图片

面板与导航

所有面板遵循“同一按键开关”原则。<leader> 键默认为 Space。

快捷键	功能
`<leader>fe` / `fE`	打开文件树（当前目录 / 主目录）
`<leader>ff` / `fF`	打开模糊查找器（当前目录 / 主目录）
`<leader>fb`	切换缓冲区列表 (`:ls`, `:b`)
`<leader>sv` / `<leader>ss`	垂直/水平分屏
`Ctrl-w` + `hjkl`	在分屏间移动焦点
`Ctrl-w q`	关闭当前分屏
`Ctrl-^` (或 `Ctrl-6`)	返回上一个缓冲区（再按一次返回）
`-` / `=` (文件树中)	向上一级 / 进入选中目录
`H` (文件树中)	切换显示/隐藏隐藏文件
`a` `r` `m` `d` (文件树中)	新建/重命名/移动/删除文件或目录

写作模式

命令	功能
`:focus [off	paragraph
`:typewriter`	光标行始终保持垂直居中
`:zen`	隐藏所有界面装饰，进入极致专注模式
`:set measure=72`	设置文本宽度（列数）
`:set line_spacing=1`	设置行间距（0-4）

笔记组合与链接

Shoin 支持 Obsidian 风格的双链，非常适合构建个人知识库。

链接：[[目标笔记名]] 创建普通链接。
嵌入：![[目标笔记名]] 嵌入另一篇笔记的内容。
块引用：![[note#Heading]] 嵌入指定标题下的内容；![[note#^blockid]] 嵌入特定块。
跟随链接：光标置于链接上，按 gf 打开目标。若目标笔记不存在，Shoin 会在当前目录下创建它。
返回：按 <C-^> 返回来源笔记。

图片嵌入

![[photo.png]] 会以与嵌入笔记相同的方式嵌入图片（支持 png, jpg, gif, webp, bmp）。

终端内显示：在 Kitty、Ghostty、WezTerm、iTerm2 等支持图像显示的终端中，图片会直接渲染在终端窗口中。
导出：shoin --export notes.md --format html 会将图片以 data: URI 的形式嵌入导出的 HTML 文件中，实现单文件自包含。

命令行导出

无需启动编辑器，直接从命令行导出文件：

# 导出为 HTML
shoin --export notes.md --format html --out notes.html

# 导出为纯文本并输出到标准输出（可用于管道）
shoin --export notes.md --format txt --stdout | pandoc -o notes.docx

配置详解

配置文件位于 ~/.config/shoin/，使用 TOML 格式。所有 *.conf 文件会被合并加载，修改后实时生效。

查看当前完整配置：shoin --print-config

常用配置示例 (~/.config/shoin/layout.conf)：

[layout]
measure    = 72      # 文本宽度（列）
typewriter = false   # 是否默认开启打字机模式
focus      = "off"   # 聚焦模式: "off", "paragraph", "sentence"

[theme]
background = "#1a1b26"  # 背景色 (Tokyo Night)
text       = "#c0caf5"  # 文字色

[input]
leader = " "            # 定义 <leader> 键

[tree]
show_hidden = false     # 文件树默认是否显示隐藏文件

自定义键绑定 (~/.config/shoin/keys.conf)：

1
2
3

[keys.normal]
"<leader>w" = "save"   # 将 <leader>w 绑定为保存命令
"s" = "operator_delete" # 将 s 键重新映射为删除操作符（保留动词语法）

更新与卸载

更新 Shoin

由于是通过 Cargo 安装，更新只需重新执行安装命令：

1	cargo install --git https://github.com/nol00p/shoin --force

卸载 Shoin

移除二进制文件：
1
cargo uninstall shoin
（可选）删除配置和数据目录：
1
rm -rf ~/.config/shoin

常见问题排查

问题：安装时提示 Rust 版本过低。

解决：使用 rustup update stable 更新 Rust 工具链。

问题：启动后界面显示异常或图标为方框。

解决：这通常是因为没有安装 Nerd Font 字体。您可以安装一个（如 JetBrainsMono Nerd Font）并在终端中设置使用，或者在配置中设置 glyphs.nerd_fonts = false 以禁用特殊图标。

问题：在 tmux 或 screen 中无法显示图片。

解决：Shoin 会检测终端类型，在 tmux 等环境中会回退到文本占位符。您可以通过环境变量强制指定协议：SHOIN_IMAGE_PROTOCOL=kitty shoin note.md。

问题：如何更改 [[note]] 链接的解析目录？

解决：Shoin 默认相对于当前文件所在目录解析链接。这是设计使然，以保持 vault 的可移植性。

通过以上步骤，您应该可以成功部署并开始使用 Shoin 了。从创建一个简单的笔记开始，逐步探索其强大的链接和导出功能，体验在终端中专注写作的乐趣。