chore: simplify project documentation

.gitignore

@@ -3,7 +3,7 @@
 # Coverage artifacts (cargo-llvm-cov)
 /lcov.info
 
-# Generated stress/perf fixture — regenerate on demand, never commit (see docs/TESTING.md)
+# Generated stress/perf fixture — regenerate with `make large-fixture`, never commit
 /fixtures/specialized/large.md
 
 *.swp

CHANGELOG.md

@@ -55,7 +55,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   (`[metadata · key=value, …]`); TUI shows the same line and can expand it
   to an inline key/value box with the new `m` key. A blank row follows the
   summary for visual separation. Opt out entirely via `metadata = false`
-  in `~/.config/termdown/config.toml`. See `docs/adr/0001-metadata-block-handling.md`.
+  in `~/.config/termdown/config.toml`.
 
 ### Changed
 - **Config location moved to the XDG path.** termdown now reads

Cargo.toml

@@ -31,7 +31,6 @@ notify = "8"
 pulldown-cmark = "0.13"
 ratatui = "0.29"
 rayon = "1"
-regex = "1"
 serde = { version = "1", features = ["derive"] }
 terminal_size = "0.4"
 toml = "0.8"

Makefile

@@ -15,7 +15,7 @@ help:
 	@echo "  coverage      - test coverage summary in the terminal (cargo-llvm-cov)"
 	@echo "  coverage-html - generate an HTML coverage report under target/llvm-cov/html"
 	@echo "  coverage-lcov - emit lcov.info for external tooling"
-	@echo "  large-fixture - (re)generate the gitignored stress fixture for manual perf runs (see docs/TESTING.md)"
+	@echo "  large-fixture - (re)generate the gitignored stress fixture for manual perf runs"
 
 fmt:
 	$(CARGO) fmt --all

README.md

@@ -2,7 +2,7 @@
 
 [中文文档](README_CN.md)
 
-Render Markdown with large-font headings in the terminal using the Kitty graphics protocol.
+termdown uses the Kitty graphics protocol to render Markdown with large-font headings in the terminal, providing a reading experience closer to a GUI Markdown reader.
 
 <table>
 <tr>
@@ -11,37 +11,26 @@ Render Markdown with large-font headings in the terminal using the Kitty graphic
 </tr>
 </table>
 
-## Motivation
+## Features
 
-Inspired by [glow](https://github.com/charmbracelet/glow) and [mdfried](https://github.com/benjajaja/mdfried).
+termdown rasterizes H1-H3 headings as PNG images and draws them directly in the terminal through the Kitty graphics protocol. It provides two modes:
 
-glow is a great terminal Markdown renderer, but headings are only distinguished by ANSI bold/color -- they can't actually be displayed at a larger size. mdfried supports image-rendered headings, but requires entering a TUI.
+- **Interactive TUI** (default) -- `termdown README.md` provides a vim/less-like experience with paging, search, a table of contents, and link navigation for longer documents.
+- **Direct output** -- `termdown --cat README.md` prints rendered Markdown like `cat`, making it suitable for short documents or piping to other programs.
 
-termdown rasterizes H1-H3 headings as PNG and paints them via the Kitty graphics protocol. Two modes share the same renderer:
-
-- **Interactive TUI** (default when a file is given) -- vim-style browser with search, Table of Contents, and link-follow navigation for longer documents.
-- **Direct output** (`--cat`, or automatic when stdout is piped / input comes from stdin) -- dump rendered Markdown straight into your terminal.
-
-H4-H6 headings always fall back to ANSI bold text.
+H4-H6 headings always use ANSI bold text instead of simulating more font sizes and weights that could reduce readability in a terminal.
 
 ## Installation
 
-### From crates.io (recommended, requires Rust)
+### Cargo
 
 ```sh
 cargo install termdown
 ```
 
 Installs into `~/.cargo/bin/`. Requires Rust 1.95+.
 
-> **Linux:** no `-dev` packages or `pkg-config` are required to build — only a
-> C toolchain (freetype is compiled from source when the system one isn't
-> found), and fontconfig is loaded lazily at run time. For system font
-> discovery (including CJK headings), install `fontconfig` plus the fonts you
-> want (e.g. `apt install fontconfig fonts-noto-cjk`). Without it, termdown
-> falls back to its bundled font.
-
-### Prebuilt binary (no Rust toolchain needed)
+### Install script
 
 ```sh
 curl -fsSL https://raw.githubusercontent.com/rrbe/termdown/master/install.sh | bash
@@ -50,7 +39,7 @@ curl -fsSL https://raw.githubusercontent.com/rrbe/termdown/master/install.sh | b
 Defaults to `/usr/local/bin`. Override the target directory with `TERMDOWN_INSTALL_DIR`.
 
 <details>
-<summary>Manual download (no script)</summary>
+<summary>Manual download</summary>
 
 ```sh
 TARGET=aarch64-apple-darwin
@@ -66,7 +55,7 @@ sudo mv termdown /usr/local/bin/
 
 </details>
 
-### From git (latest development snapshot)
+### Install from source
 
 ```sh
 cargo install --git https://github.com/rrbe/termdown
@@ -106,18 +95,20 @@ termdown --help
 termdown --watch notes.md
 ```
 
-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.
+## Documentation
+
+- [Usage guide](docs/USAGE.md)
+- [Project overview](docs/OVERVIEW.md)
+- Configuration and defaults: [`config.example.toml`](config.example.toml)
+- Configuration file: `~/.config/termdown/config.toml`
 
 ## Terminal Support
 
-Requires a terminal with **Kitty graphics protocol** support:
+Requires a terminal with **Kitty graphics protocol** support, such as:
 
-- [Ghostty](https://ghostty.org)
 - [Kitty](https://sw.kovidgoyal.net/kitty/)
-- [WezTerm](https://wezfurlong.org/wezterm/)
 - [iTerm2](https://iterm2.com)
-
-On unsupported terminals, termdown prints a warning and heading images may not display correctly. H4-H6 headings always render as plain ANSI bold text.
+- [Ghostty](https://ghostty.org)
 
 ## License
 

README_CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md)
 
-在终端中以大字体标题渲染 Markdown，让观感更接近 GUI Markdown 阅读器的体验，基于 Kitty 图形协议。
+termdown 基于 Kitty 图形协议，在终端中以大字体标题渲染 Markdown，提供更接近 GUI Markdown 阅读器的阅读体验。
 
 <table>
 <tr>
@@ -11,37 +11,32 @@
 </tr>
 </table>
 
-## 为什么做这个
-
-本项目受 [glow](https://github.com/charmbracelet/glow) 和 [mdfried](https://github.com/benjajaja/mdfried) 启发。
-
-- **glow** 不支持放大标题字体
-- **mdfried** 支持放大 markdown 标题，但个人感觉可以做的更美观一点
+## 功能
 
 termdown 将 H1-H3 标题栅格化为 PNG 图片，通过 Kitty 图形协议直接绘制到终端。提供两种使用模式：
 
-- **交互式 TUI**（默认）—— `termdown README.md`，类 vim/less 的体验，支持常见的翻页、搜索等快捷键，支持查看 TOC、链接跳转，适合阅读较长文档。
-- **直接输出**（`--cat`，或当 stdout 被管道/重定向、输入来自 stdin 时自动启用）—— 像 `cat` 一样轻量、管道友好，把渲染后的 Markdown 直接打到终端。
+- **交互式 TUI**（默认）—— `termdown README.md`，提供类似 vim/less 的体验，支持翻页、搜索、查看目录和链接跳转，适合阅读较长文档。
+- **直接输出** —— `termdown --cat README.md`，像 `cat` 一样直接输出渲染后的 Markdown，适合查看短文档或通过管道交给其他程序处理。
 
-H4-H6 标题始终以 ANSI 粗体文本渲染。不想让文档加入那么多种字重，那样反而损害可读性。
+H4-H6 标题始终以 ANSI 粗体文本渲染，不再模拟更多字号和字重，以免损害终端中的可读性。
 
 ## 安装
 
-### 从 crates.io（推荐，需要 Rust）
+### Cargo
 
 ```sh
 cargo install termdown
 ```
 
 安装到 `~/.cargo/bin/`。需要 Rust 1.95+。
 
-### 安装脚本（无需 Rust 工具链）
+### 脚本安装
 
 ```sh
 curl -fsSL https://raw.githubusercontent.com/rrbe/termdown/master/install.sh | bash
 ```
 
-默认装到 `/usr/local/bin`。用 `TERMDOWN_INSTALL_DIR` 覆盖安装目录。
+默认装到 `/usr/local/bin`。可以用 `TERMDOWN_INSTALL_DIR` 覆盖安装目录。
 
 <details>
 <summary>手动下载</summary>
@@ -60,7 +55,7 @@ sudo mv termdown /usr/local/bin/
 
 </details>
 
-### 从源码
+### 源码安装
 
 ```sh
 cargo install --git https://github.com/rrbe/termdown
@@ -100,18 +95,20 @@ termdown --help
 termdown --watch notes.md
 ```
 
-完整的命令行参数、TUI 快捷键、配置项和已知问题都在 **[使用指南](docs/USAGE_CN.md)**。配置是可选的，位于 `~/.config/termdown/config.toml` —— 全部默认值见 [`config.example.toml`](config.example.toml)。
+## 文档
+
+- [使用指南](docs/USAGE_CN.md)
+- [项目概览](docs/OVERVIEW.md)
+- 配置和默认值：[`config.example.toml`](config.example.toml)
+- 配置文件：`~/.config/termdown/config.toml`
 
 ## 终端支持
 
-需要支持 **Kitty 图形协议** 的终端（目前仅在 Ghostty 和 iTerm2 上测试过）：
+需要支持 **Kitty 图形协议** 的终端，比如：
 
-- [Ghostty](https://ghostty.org)
 - [Kitty](https://sw.kovidgoyal.net/kitty/)
-- [WezTerm](https://wezfurlong.org/wezterm/)
 - [iTerm2](https://iterm2.com)
-
-不支持的终端会打印警告。H4-H6 标题始终以 ANSI 粗体文本渲染。
+- [Ghostty](https://ghostty.org)
 
 ## 许可证
 

TODO.md

@@ -1,13 +1,5 @@
-- [ ] 测试 html 标签支持
-- [ ] 图片支持
-- [ ] 长文本换行时缩进的处理
-- [ ] 找出真实 MSRV 并下调 `rust-version`(当前 `1.95` 是跟本地对齐,触达面窄)
-  - 本地跑 `cargo install cargo-msrv && cargo msrv find`,二分出最低能编译的版本
-  - 同步更新 `Cargo.toml` 的 `rust-version` 和 `README.md` 里的 "Requires Rust X.Y+"
-  - 在 `.github/workflows/ci.yml` 加一个 `msrv` job(`cargo check --all-targets` on pinned toolchain),防止以后 PR 悄悄抬高 MSRV
-- [x] 测试 markdown metadata 支持
-- [ ] 检测文件变化
-- [x] 文件到顶、末尾时，播放声音提示，增加喇叭icon
-- [ ] t 开启目录时，支持左右等方向键在目录和内容之间切换，并可以有一些界面上的 focus 提示
-- [ ] 整理项目文档
-- [x] 整理测试用的 markdown 文件，现在太乱 
+- [ ] 完善 HTML 标签测试
+- [ ] 支持正文图片
+- [ ] 修复长文本换行后的缩进
+- [ ] 测定并在 CI 固定真实 MSRV
+- [ ] 支持目录与正文的键盘焦点切换