阅境｜让知识更好读
把 Markdown 与配图，变成一份可以独立打开、自由调整阅读体验的 HTML 文档。
适合知识笔记、图文教程、课程讲义与长篇学习资料。用 Markdown 维护内容，用同一套页面规则展示；也可以让 AI 按大纲写作、制作配图，再调用固定程序生成阅读版。
无需注册账号，无需运行后台服务。生成的 HTML 已包含正文、样式、阅读脚本与全部图片，可以离线打开、发送给别人，或发布为网页。
在线体验 · 演示源文件 · AI 使用说明 · 完整示例 · 内容组件 · 在线展示设置
点击"在线体验"可直接调整配色、字号、留白和字体。仓库里的 HTML 文件用于下载或查看源码；下载后也能离线打开。
可以获得怎样的阅读体验
| 功能 | 实际体验 |
|---|---|
| 集中的阅读设置 | 平时隐藏，点击后调整，改动即时生效 |
| 四种配色 | 白色、纸色、浅绿、深黑；背景质感单独选择 |
| 正文字号 | 16--36 px，按 1 px 调整 |
| 连续调整正文宽度 | 左右各留白 0--40%，带可点击的参考圆点；收起目录后可铺满窗口 |
| 字体与段落 | 黑体、宋体、楷体；行距和首行缩进独立调整 |
| 目录与定位 | 电脑左侧目录、手机折叠目录，当前章节随阅读更新 |
| 图文与技术内容 | 图片点击放大，宽表格与代码局部滚动，支持现成提示块和补充说明 |
| 单文件携带 | 图片完整内嵌，不需要把 assets 一起发给读者 |
首页只保留居中的文档名称、作者、发表日期和字数。固定标题 42 px，文章信息 22 px 加粗；字体跟随阅读选择。阅读偏好在浏览器允许时保存在本地。
一条内容制作流程
text
确认大纲 → AI 撰写正文并制作配图 → Markdown + assets + 文章配置
↓
固定程序生成与校验
↓
独立 HTML 阅读版AI 负责内容，程序负责复用页面框架与阅读功能。模板不要求每一篇文章都出现封面、提示块或所有组件；根据内容需要使用即可。
把仓库链接交给 AI，能直接用吗
可以把仓库链接作为入口。要稳定地生成文件，AI 还需要取得仓库文件并能运行 Python。
| 你使用的 AI 环境 | 推荐方式 |
|---|---|
| 能获取仓库文件，并能运行 Python | 提供仓库链接、大纲和下面的要求，让它下载或克隆完整项目后生成 |
| 能读取上传文件，并能运行 Python | 下载仓库 ZIP，上传给 AI，再提供大纲 |
| 只能浏览网页或文字聊天 | 可以了解模板规则；不能仅凭读到 README 就保证生成并验证完整文件 |
不要求安装 skill 或 plugin。README 是公开入口，给AI的模板使用要求.md 是完整执行约定，程序文件是实际生成工具。需要适配某种 AI 产品时，可以另外做接入层，模板本身保持独立。
复制仓库链接，并一起发送这段要求：
请读取我提供的仓库链接，先看 README.md 和《给AI的模板使用要求.md》。获取完整仓库文件，按照我确认的大纲撰写正文、制作必要配图，在独立文章文件夹交付 Markdown、assets、document.json 和 HTML。使用仓库里的固定生成程序与校验程序，保持页面格式和阅读功能一致；HTML 图片必须完整内嵌。署名和发表日期使用我提供的信息，未知日期留空显示。不要只参照截图重新写页面；请实际运行程序，并说明生成和检查结果。
再附上：大纲、文档名称、你的署名、输出位置和发表日期（可暂不填写）。图片制作取决于当前 AI 可用的制图工具；这个项目不包含自动写作或图像生成服务。
每篇新文档交付什么
text
你的文档文件夹/
├─ document.json # 文章名称、作者、日期与文件路径
├─ 文章.md # 内容源文件，图片用 assets 相对路径
├─ 文章.html # 程序生成，文字、样式、脚本、图片全部内嵌
└─ assets/ # 原始配图，供 Markdown 阅读和以后修改
├─ 图1.png
└─ 图2.svgMarkdown 和 assets 是可维护的原稿。HTML 是可以单独携带、离线阅读或放到 GitHub Pages 上的阅读版。正常的参考文献网页链接仍可保留；点击它们才需要访问相应网站。
本地使用：两步生成
先下载仓库 ZIP 并解压，或使用 Git 获取项目：
sh
git clone https://github.com/GRITJW/reading-template.git
cd reading-template以下命令在模板根目录执行。生成工具需要 Python 3.10 以上及 requirements.txt 中的两个包。请使用已安装这些依赖的 Python；如果命令名不是 python，可替换成实际解释器命令或路径。
先安装构建依赖（只在生成时需要；阅读 HTML 不需要安装）：
sh
python -m pip install -r requirements.txt1. 初始化一篇新文档。 目标文件夹必须是新文件夹或空文件夹。已有文档可直接准备 document.json，不用再次初始化。
powershell
python "源文件/init.py" "新文档" --title "你的文档名称" --author "你的署名"需要发表日期时添加 --date "YYYY-MM-DD" 并填写真实日期；未确定则省略。署名可自行指定，程序默认作者为"石头开会"。初始化后，AI 按大纲完成 文章.md，把真实配图保存到 assets/，在 Markdown 中引用它们。
2. 用配置生成并自动校验 HTML。
powershell
python "源文件/build.py" --config "新文档/document.json"看到 "status": "passed" 表示生成与内置检查通过。后续修改正文或图片后，重复第二步即可。程序不调用 AI，也不代替正文写作或图片制作；它负责把已完成的内容稳定地装入固定页面。
也可使用 生成文档.ps1 -Config '完整配置路径'；遇到本机脚本运行限制时，使用上面的 Python 命令即可，无需更改系统设置。
文章配置
document.json 采用 UTF-8，路径相对于它所在的文章文件夹。可照抄示例项目，仅修改文章信息：
json
{
"schema_version": 1,
"template_id": "knowledge-reader-v5",
"source": "文章.md",
"output": "文章.html",
"metadata": {
"title": "你的文档名称",
"author": "石头开会",
"publication_date": null
},
"reading": {
"margin_percent": 10
}
}title 必须与 Markdown 唯一的 # 一级标题 一致；日期使用 "YYYY-MM-DD" 或 null。margin_percent 是左右每侧的初始留白，默认 10，允许 0---40 的整数。没有必要改动时保持默认。这里不提供 CSS、标题字号或另一套排版参数。
如何保证样式稳定
源文件/shell.html固定页面结构，reader.css固定样式，reader.js固定阅读功能。template-lock.json记录上述三份文件的校验值。生成时发现改动就停止，不自动接受新样式。- 程序自动生成目录、内嵌图片、统计字数，然后核对输出的样式与脚本、图片数据、目录锚点、文章信息和字号范围。
- 找不到图片、引用远程图片、SVG 内仍依赖别的文件、配置与标题不一致时会报错。校验通过前不替换已有 HTML。
- 同样的原稿、图片、配置、模板和依赖版本，重复生成的 HTML 内容一致。读者在浏览器中保存的配色、字体和字号仍会优先生效；设备可用字体不同，也会有正常的字体替代。
需要重新检查已有 HTML 时：
powershell
python "源文件/validate.py" --config "新文档/document.json"模板文件夹怎么用
| 文件或文件夹 | 用途 |
|---|---|
| README.md | 从这里开始 |
| 给AI的模板使用要求.md | 给后续 AI 的完整操作约定 |
| 设计规范与使用说明.md | 已确认的页面规则 |
| 内容组件约定.md | 标题、配图、引用、表格、代码和提示块怎么写 |
| 模板预览.html | 当前唯一的主预览入口 |
| 示例项目/ | 完整的 Markdown、配置、图片与生成结果 |
| 源文件/ | 固定视觉文件与生成、初始化、校验程序 |
| document.schema.json | 配置字段的机器可读说明；生成程序也会自行校验 |
| template-lock.json | 固定视觉文件的版本校验值 |
| 测试/ | 维护工具时使用，日常写作不用操作 |
只有明确要调整模板本身时，才修改固定视觉文件并更新版本。日常写作只修改文章项目中的 Markdown、图片与文章配置。
迁移或交给其他 AI 时，复制整个模板文件夹即可。HTML 浏览时无需 Python，也无需同时带上这个工具包。