rrbe · rrbe · Jun 1, 2026 · Jun 1, 2026 · Jun 1, 2026 · Jun 1, 2026
diff --git a/Cargo.toml b/Cargo.toml
@@ -14,7 +14,6 @@ rust-version = "1.95"
 exclude = [
     "CLAUDE.md",
     "TODO.md",
-    "TEST_PLAN.md",
     "docs/",
     ".github/",
     "install.sh",

diff --git a/README.md b/README.md
@@ -6,8 +6,8 @@ Render Markdown with large-font headings in the terminal using the Kitty graphic
 
 <table>
 <tr>
-<td><img src="https://raw.githubusercontent.com/rrbe/termdown/v0.4.0/docs/screenshots/termdown_render_cn_demo.png" width="380" alt="termdown rendering the Chinese README" /></td>
-<td><img src="https://raw.githubusercontent.com/rrbe/termdown/v0.4.0/docs/screenshots/termdown_render_en_tui_demo.png" width="380" alt="termdown rendering the English README in TUI mode" /></td>
+<td><img src="https://raw.githubusercontent.com/rrbe/termdown/master/docs/screenshots/termdown_render_cn_demo.png" width="380" alt="termdown rendering the Chinese README" /></td>
+<td><img src="https://raw.githubusercontent.com/rrbe/termdown/master/docs/screenshots/termdown_render_en_tui_demo.png" width="380" alt="termdown rendering the English README in TUI mode" /></td>
 </tr>
 </table>
 
@@ -87,111 +87,16 @@ rm -rf ~/.config/termdown
 # Open a file in the interactive TUI (default)
 termdown README.md
 
-# Force plain cat-style output (non-interactive, pipe-friendly)
+# Plain cat-style output (non-interactive, pipe-friendly)
 termdown --cat README.md
-
-# Pipe from stdin (always cat-style — TUI needs a real file)
 cat notes.md | termdown
 
-# Piped or redirected stdout also falls back to cat
-termdown README.md | less
-
-# Use a specific theme instead of auto-detect
+# Pick a theme; show help
 termdown --theme light README.md
-
-# Disable the edge-scroll bell (also configurable via `bell = false`)
-termdown --no-bell README.md
-
-# View help
 termdown --help
-termdown --version
 ```
 
-### TUI mode
-
-The TUI launches automatically whenever you pass a file and stdout is a real
-terminal:
-
-```sh
-termdown README.md
-```
-
-Key bindings:
-
-| Key | Action |
-|---|---|
-| `j` / `↓` | Scroll down one line |
-| `k` / `↑` | Scroll up one line |
-| `d` / `u` | Half page down / up |
-| `f` / `Space` / `PgDn` | Full page down |
-| `b` / `PgUp` | Full page up |
-| `gg` / `G` | Jump to start / end |
-| `]` / `[` | Next / previous heading |
-| `t` | Toggle Table of Contents panel |
-| `/` | Search forward |
-| `n` / `N` | Next / previous match |
-| `?` | Toggle keyboard-shortcut help overlay |
-| `Enter` | Follow link (overlay picker if multiple visible) |
-| `o` / `i` | Back / forward across followed `.md` links |
-| `q` / `Ctrl-C` | Quit |
-
-TUI mode requires a file path; stdin input is not supported.
-
-## Configuration
-
-termdown reads configuration from `~/.config/termdown/config.toml` (or
-`$XDG_CONFIG_HOME/termdown/config.toml` if `XDG_CONFIG_HOME` is set). All
-settings are optional; see [`config.example.toml`](config.example.toml) for a
-copy-pasteable file with every default.
-
-```toml
-# Theme: "auto" (default), "dark", or "light"
-# Auto-detection queries the terminal background color via OSC 11.
-theme = "auto"
-
-# Vim-style edge bell: emit a terminal BEL when you scroll past the
-# top/bottom of the document. The terminal emulator decides the visible
-# effect (audible beep, title-bar 🔔, dock bounce, …). Default true.
-# CLI: `--no-bell`.
-bell = true
-
-[font.heading]
-# English heading font (sans-serif recommended)
-latin = "Inter"
-
-# CJK heading font
-cjk = "LXGW WenKai"
-
-# Emoji / symbol fallback font for image-rendered headings (optional)
-emoji = "Apple Color Emoji"
-```
-
-Headings with mixed scripts (e.g. "Hello 世界") will render each character with the appropriate font automatically.
-Standalone emoji in H1-H3 headings are also rendered via font fallback where possible.
-
-> **Note:** Body text is rendered as plain ANSI text -- its font is determined by your terminal emulator settings, not by termdown. To change the body font, configure your terminal directly.
-
-If no config file exists, termdown uses platform-specific defaults and falls back to an embedded SourceSerif4 font.
-
-### Platform default heading fonts
-
-**Latin** (sans-serif):
-
-| macOS | Linux | Windows |
-|-------|-------|---------|
-| Avenir | Inter | Segoe UI |
-| Avenir Next | Noto Sans | Arial |
-| Futura | DejaVu Sans | Verdana |
-| Helvetica Neue | Liberation Sans | |
-
-**CJK**:
-
-| macOS | Linux | Windows |
-|-------|-------|---------|
-| Noto Serif CJK SC | Noto Serif CJK SC | SimSun |
-| Source Han Serif SC | Source Han Serif SC | KaiTi |
-| Songti SC | Noto Serif | Microsoft YaHei |
-| STSong | DejaVu Serif | |
+The full CLI reference, TUI key bindings, configuration, and known issues live in the **[Usage Guide](docs/USAGE.md)**. Configuration is optional and lives at `~/.config/termdown/config.toml` -- see [`config.example.toml`](config.example.toml) for every default.
 
 ## Terminal Support
 
@@ -202,16 +107,7 @@ Requires a terminal with **Kitty graphics protocol** support:
 - [WezTerm](https://wezfurlong.org/wezterm/)
 - [iTerm2](https://iterm2.com)
 
-On unsupported terminals, termdown will print a warning and heading images may not display correctly. H4-H6 headings always render as plain ANSI bold text.
-
-## Known Issues
-
-- **Line wrapping** -- long lines may not wrap correctly when mixed with ANSI escape sequences
-- **Terminal compatibility** -- only tested on Ghostty and iTerm2; other Kitty-protocol terminals may behave differently
-- **Font selection & fallback** -- weight matching relies on platform font APIs (Core Text / fontconfig) which may not always resolve to the expected variant
-- **Theme detection** -- auto-detection relies on OSC 11 terminal responses; if your terminal does not support this, use `--theme` or the config file to set the theme manually
-- **Complex emoji sequences** -- ZWJ-heavy emoji sequences (family/grouping variants, some skin-tone combinations) may still render as separate glyphs because heading layout does not perform full text shaping
-- **TUI help popup vs heading images** -- in TUI mode, the `?` help overlay is drawn on the text layer, while heading images live on Kitty's graphics layer (always on top of text). Any heading image overlapping the popup area is temporarily removed while the popup is open and restored when it closes -- this is a Kitty graphics protocol limitation, not a bug
+On unsupported terminals, termdown prints a warning and heading images may not display correctly. H4-H6 headings always render as plain ANSI bold text.
 
 ## License
 

diff --git a/README_CN.md b/README_CN.md
@@ -1,11 +1,13 @@
 # Termdown
 
+[English](README.md)
+
 在终端中以大字体标题渲染 Markdown，让观感更接近 GUI Markdown 阅读器的体验，基于 Kitty 图形协议。
 
 <table>
 <tr>
-<td><img src="https://raw.githubusercontent.com/rrbe/termdown/v0.4.0/docs/screenshots/termdown_render_cn_demo.png" width="380" alt="termdown 渲染中文 README" /></td>
-<td><img src="https://raw.githubusercontent.com/rrbe/termdown/v0.4.0/docs/screenshots/termdown_render_en_tui_demo.png" width="380" alt="termdown 在 TUI 模式下渲染英文 README" /></td>
+<td><img src="https://raw.githubusercontent.com/rrbe/termdown/master/docs/screenshots/termdown_render_cn_demo.png" width="380" alt="termdown 渲染中文 README" /></td>
+<td><img src="https://raw.githubusercontent.com/rrbe/termdown/master/docs/screenshots/termdown_render_en_tui_demo.png" width="380" alt="termdown 在 TUI 模式下渲染英文 README" /></td>
 </tr>
 </table>
 
@@ -25,7 +27,15 @@ H4-H6 标题始终以 ANSI 粗体文本渲染。不想让文档加入那么多
 
 ## 安装
 
-### 安装脚本
+### 从 crates.io（推荐，需要 Rust）
+
+```sh
+cargo install termdown
+```
+
+安装到 `~/.cargo/bin/`。需要 Rust 1.95+。
+
+### 安装脚本（无需 Rust 工具链）
 
 ```sh
 curl -fsSL https://raw.githubusercontent.com/rrbe/termdown/master/install.sh | bash
@@ -50,14 +60,12 @@ sudo mv termdown /usr/local/bin/
 
 </details>
 
-### 源码安装
+### 从源码
 
 ```sh
 cargo install --git https://github.com/rrbe/termdown
 ```
 
-安装到 `~/.cargo/bin/`。
-
 ## 卸载
 
 ```sh
@@ -80,107 +88,16 @@ rm -rf ~/.config/termdown
 # 默认进入交互式 TUI
 termdown README.md
 
-# 强制使用 cat 风格的纯输出（非交互、管道友好）
+# cat 风格纯输出（非交互、管道友好）
 termdown --cat README.md
-
-# 从 stdin 管道输入（始终是 cat 模式 —— TUI 需要真实文件）
 cat notes.md | termdown
 
-# stdout 被管道/重定向时也会自动回退到 cat
-termdown README.md | less
-
-# 指定主题（不使用终端亮色、暗色主题自动检测）
+# 指定主题；查看帮助
 termdown --theme light README.md
-
-# 关闭文档到顶/到底时的提示铃声（也可在配置中设 `bell = false`）
-termdown --no-bell README.md
-
-# 查看帮助
 termdown --help
-termdown --version
-```
-
-### TUI 模式
-
-当传入文件且 stdout 为真实终端时，自动进入 TUI：
-
-```sh
-termdown README.md
 ```
 
-按键绑定：
-
-| 按键                   | 动作                                         |
-| ---------------------- | -------------------------------------------- |
-| `j` / `↓`              | 向下滚动一行                                 |
-| `k` / `↑`              | 向上滚动一行                                 |
-| `d` / `u`              | 半屏向下 / 向上                              |
-| `f` / `Space` / `PgDn` | 整屏向下                                     |
-| `b` / `PgUp`           | 整屏向上                                     |
-| `gg` / `G`             | 跳到文档开头 / 末尾                          |
-| `]` / `[`              | 下一个 / 上一个标题                          |
-| `t`                    | 切换目录面板                                 |
-| `/`                    | 正向搜索                                     |
-| `n` / `N`              | 下一个 / 上一个匹配                          |
-| `?`                    | 切换快捷键帮助弹窗                           |
-| `Enter`                | 打开链接（屏幕中有多个链接时显示序号选择器） |
-| `o` / `i`              | 在已跳转的 `.md` 文档之间前进 / 后退         |
-| `q` / `Ctrl-C`         | 退出                                         |
-
-TUI 模式需要指定文件路径，不支持从 stdin 读取。
-
-## 配置
-
-配置文件位于 `~/.config/termdown/config.toml`（若设置了 `XDG_CONFIG_HOME`，则为
-`$XDG_CONFIG_HOME/termdown/config.toml`）。所有配置项均为可选；仓库根目录的
-[`config.example.toml`](config.example.toml) 提供了一份包含全部默认值、可直接复制的示例。
-
-```toml
-# 主题："auto"（默认）、"dark" 或 "light"
-# 自动检测通过 OSC 11 查询终端背景色。
-theme = "auto"
-
-# 文档到顶/到底时向终端发一次 BEL。具体表现（响铃、标题栏 🔔、
-# dock 弹跳等）由终端模拟器决定。默认 true，命令行可用 `--no-bell` 关闭。
-bell = true
-
-[font.heading]
-# 英文标题字体（推荐无衬线字体）
-latin = "Inter"
-
-# 中文标题字体
-cjk = "LXGW WenKai"
-
-# 图片标题里的 emoji / 符号 fallback 字体（可选）
-emoji = "Apple Color Emoji"
-```
-
-混合语言标题（如 "Hello 世界"）会自动按字符选择对应字体渲染。
-H1-H3 标题中的单个 emoji 也会通过 fallback 字体尽量渲染出来。
-
-> **注意：** 正文以 ANSI 纯文本输出，字体由终端模拟器决定，不受 termdown 控制。
-
-未配置时使用平台默认字体，最终回退到内嵌的 SourceSerif4 字体。
-
-### 平台默认标题字体
-
-**Latin**（无衬线）：
-
-| macOS          | Linux           | Windows  |
-| -------------- | --------------- | -------- |
-| Avenir         | Inter           | Segoe UI |
-| Avenir Next    | Noto Sans       | Arial    |
-| Futura         | DejaVu Sans     | Verdana  |
-| Helvetica Neue | Liberation Sans |          |
-
-**CJK**：
-
-| macOS               | Linux               | Windows         |
-| ------------------- | ------------------- | --------------- |
-| Noto Serif CJK SC   | Noto Serif CJK SC   | SimSun          |
-| Source Han Serif SC | Source Han Serif SC | KaiTi           |
-| Songti SC           | Noto Serif          | Microsoft YaHei |
-| STSong              | DejaVu Serif        |                 |
+完整的命令行参数、TUI 快捷键、配置项和已知问题都在 **[使用指南](docs/USAGE_CN.md)**。配置是可选的，位于 `~/.config/termdown/config.toml` —— 全部默认值见 [`config.example.toml`](config.example.toml)。
 
 ## 终端支持
 
@@ -193,14 +110,6 @@ H1-H3 标题中的单个 emoji 也会通过 fallback 字体尽量渲染出来。
 
 不支持的终端会打印警告。H4-H6 标题始终以 ANSI 粗体文本渲染。
 
-## 已知问题
-
-- **换行显示** -- 含 ANSI 转义序列的长行可能无法正确换行
-- **字体选择与降级** -- 字体粗细匹配依赖平台 API（Core Text / fontconfig），不一定能解析到预期的字重变体
-- **主题检测** -- 自动检测依赖终端对 OSC 11 的响应；如终端不支持，请通过 `--theme` 或配置文件手动指定主题
-- **复杂 emoji 序列** -- 依赖 ZWJ 的复杂 emoji（例如家庭/群组类组合、部分肤色组合）目前仍可能拆成多个字形，因为标题渲染还没有完整文本 shaping
-- **TUI 帮助弹窗与标题图片** -- TUI 模式下 `?` 帮助弹窗绘制在文字层，而标题图片位于 Kitty graphics 层（始终覆盖在文字之上）。与弹窗区域重叠的标题图片会在弹窗打开时被临时移除，关闭后自动恢复 —— 这是 Kitty graphics 协议的限制
-
 ## 许可证
 
 [Apache-2.0](LICENSE)