背景介绍：最近在通勤上时间较多，考虑通过移动设备连接家里的文件服务器（树莓派5）来阅读各种文档，利用通勤时间来学习一些东西。通过移动终端（手机，墨水屏阅读器）利用终端模拟器来连接设备，考虑使用终端的情况，最好是能够在 terminal 渲染 markdown 文件，提升阅读体验。

主要是使用 mdcat 在终端渲染 markdown 文件，由于 mdcat 没有提供 aarch64 的版本，因此核心是解决 mdcat 在树莓派的编译适配+终端特性兼容（远程场景没有 GUI/专有图片协议）。

1 解决树莓派5 mdcat 编译/安装

树莓派 5 是aarch64（ARM64）架构，官方无预编译包，需手动编译，且要适配远程终端的限制，没有 iTerm2/Kitty 等专有协议，仅 ANSI 兼容。

1) 安装编译依赖

# 更新系统包
sudo apt update && sudo apt upgrade -y

# 安装基础编译工具+依赖
sudo apt install -y build-essential libcurl4-openssl-dev pkg-config git

# 安装Rust（编译mdcat的核心）
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# 选择默认安装（1），安装完成后生效环境变量
source $HOME/.cargo/env

2) 编译 mdcat（适配远程终端，禁用专有图片协议）

远程终端（移动设备）几乎不支持 iTerm2/Kitty 的图片渲染，在编译时可以禁用 svg/image-processing 特性，减少依赖且适配纯 ANSI 输出：

# 克隆源码
git clone https://github.com/swsnr/mdcat.git
cd mdcat

# 编译（禁用图片相关特性，仅保留核心ANSI渲染）
cargo build --release --no-default-features --features "default-no-svg"

# 安装到系统路径（全局可用）
sudo cp target/release/mdcat /usr/local/bin/
sudo cp target/release/mdless /usr/local/bin/  # 带分页的mdcat

# 验证安装
mdcat --version

3) 编译报错

最新的 mdcat 源码代码检查规则严格，禁用了未使用的结构体 Osc8Links，我们编译时禁用了部分特性，导致这个结构体没有被调用，触发了报错。

error: struct `Osc8Links` is never constructed
  --> pulldown-cmark-mdcat/src/terminal/osc.rs:24:12
   |
24 | pub struct Osc8Links;
   |            ^^^^^^^^^
   |
note: the lint level is defined here
  --> pulldown-cmark-mdcat/src/lib.rs:37:9
   |
37 | #![deny(warnings, missing_docs, clippy::all)]
   |         ^^^^^^^^
   = note: `#[deny(dead_code)]` implied by `#[deny(warnings)]`

error: could not compile `pulldown-cmark-mdcat` (lib) due to 1 previous error

考虑手动修改源码，忽略 dead_code 错误。直接修改源码的代码检查规则，跳过未使用代码的报错，不影响 mdcat 的核心功能

cd mdcat

# 编辑 pulldown-cmark-mdcat/src/lib.rs 文件，修改其中的代码检查配置，跳过 dead_code 报错：
vim pulldown-cmark-mdcat/src/lib.rs
# 找到文件中第 37 行（对应报错信息中的行）：#![deny(warnings, missing_docs, clippy::all)]
# 修改方法：保留 deny，但明确排除 dead_code（精准跳过当前报错）
# 修改后如下：
#![deny(warnings, missing_docs, clippy::all)]
#![allow(dead_code)]

修改完成后，保存退出，重新编译。

2 远程终端渲染 markdown 实践

远程链接（SSH）的终端无 GUI、无专有图片协议，重点优化ANSI 格式化、分页、适配移动终端小屏幕：

• 基础渲染（纯文本+语法高亮）

# 渲染单个Markdown文件
mdcat your-doc.md

# 从标准输入渲染（比如管道）
cat README.md | mdcat

• 分页查看

# 用mdless（mdcat 的分页版）或mdcat --paginate，支持上下翻页、搜索，移动终端操作更友好
# 分页查看（默认用系统PAGER，如less）
mdless your-doc.md

# 强制用less并配置移动终端友好参数（行号、高亮搜索）
MDCAT_PAGER="less -N -i" mdless your-doc.md

# 限制输出列数（比如80列，适配手机屏幕）
mdcat --columns 80 your-doc.md

# 仅用ANSI格式（兼容所有终端，包括极简移动终端）
mdcat --ansi your-doc.md

# 禁用颜色（如果终端配色冲突）
mdcat --no-colour your-doc.md