使用指南

• 这是什么
• 认识首页
• 读一篇
• 卡片上的按钮
• 放进自己的文件
• 订阅别人的文章
• 在手机上用
• 公共目录与投稿
• 订阅本站
• 常见问题

0这是什么

知树阅读是一个个人数字图书馆：站长把笔记、书、PDF 和网页小工具放进一个文件夹，它们就变成网页上一张张卡片。不用注册，不用登录，打开就能读。你可以做三件事：

1认识首页

1. 我的书架 / 公共目录：两个空间，点一下切换。“我的书架”是这个站点自己的书和你放进来的文件；“公共目录”见第 6 节。
2. 分类和标签：点分类只看这一类，点标签按主题筛选。下面的“卡片目录”列出每一类里文章的标题，点一下就跳到那张卡片。
3. 搜索：标题、摘要、关键词一起搜。按 / 键直接跳到搜索框。打开右边的“搜正文”，连书里的文字也搜，结果带上下文和“第 N 页”，点开直接跳到那一处（只在“我的书架”里，在你的浏览器里完成，不上传任何东西）。公共目录只搜书籍信息：标题、作者、语言、页数、目录、摘要和关键词。
4. 卡片：封面、标题、摘要、阅读时间。点它开始阅读。右上角的小标记是文件类型（MD / PDF / TXT / APP……）；“APP”是一个网页小工具。
5. 添加：把你自己的文件放进来，见第 4 节。

搜索框右边还有：全部 / 中 / EN（只看某种语言的内容）、排序（最近添加 / 发布日期 / 最近阅读 / 标题；公共目录按最新排列）、列表 / 卡片视图、订阅。左下角可以切换界面语言（“自动”跟随系统，旁边一个“中 / EN”按钮点一下换成另一种）和主题（跟随系统 / 浅色 / 深色）。

2读一篇

点任意一张卡片就进入阅读器。所有格式共用同一排按钮：

1. 返回：回到书架（也可以按 Esc）。
2. 上一篇 / 下一篇：按当前列表的顺序翻页（也可以按 ← →）。
3. 目录：取文章里的标题，点一下跳到那一节，并标出读到哪里；“书签”页在旁边。
4. 阅读设置（Aa）：换颜色、调字号，见下图。
5. 保存：下载这一篇的网页（HTML），或者打印 / 存为 PDF。原样显示的网页只能打印；PDF 用浏览器自己的功能保存，这个按钮是灰的。
6. 加书签：记下现在读到的位置，之后在“书签”里点一下就回来。
7. 精选 / 新标签打开：收藏整篇；或者在新标签页里单独打开这一篇。

滚动时会自动记住进度，下次打开回到原来的位置；首页最上面的“继续阅读”列出读到一半的几篇。手机上，目录、阅读设置、保存这几个面板打开后，点一下页面上空着的地方就收回去（目录面板也可以向右滑收回），左侧列表同理。

3卡片上的按钮

4放进你自己的文件

1. 点右上角的 添加（或者直接把文件拖进页面）。
2. 点虚线框选文件，可以一次选很多个。支持 HTML、Markdown、TXT、PDF，单个不超过 30 MB。
3. 每个文件可以改标题和摘要；选好合集和分类。
4. 点 保存。页面会自动切到这个合集。

备份与恢复：换设备、防丢失

你的文件、合集、订阅、阅读进度和书签只存在这个浏览器里，所以换设备或清除网站数据之前，先做一份备份。点左下角的 备份与恢复：

• 导出完整备份：一个 .zip，里面有你添加的所有文件和全部设置。
• 只导出书单和设置：一个很小的 .json，不含文件内容，适合先把收藏的链接、订阅、合集和阅读进度带到另一台设备。
• 恢复：选择备份文件，页面先告诉你里面有什么、哪些已经在这里了，点“合并到我的书架”才会导入。只会合并，不会删除你现有的任何东西；内容相同的文件不会重复添加。

备份文件由浏览器生成，保存在你自己的设备上，不经过服务器。站点自带的书和你“连接”的本机文件夹里的文件不在备份里。首页第一次打开时的“这是什么”说明，关掉以后可以在左下角点“这是什么”再看。

同步（可选）：几台设备用同一个书架

站点开通了同步服务时，左下角会有一个 同步 按钮（没有就是没开通）。它是可选的，不开也能完整使用；不用注册，不用密码。

1. 在第一台设备上点 同步 → 开启同步，生成同步码，把显示的同步码马上保存好（比如存进密码管理器）。
2. 在另一台设备上点 同步，在“已经在别的设备上开过同步？”里输入同步码，点 连接。
3. 以后改动会在几秒后自动同步，回到页面时也会同步一次；也可以随时点“立即同步”。

• 同步什么：书单、收藏的链接、订阅清单、合集、阅读进度、书签、星标和置顶；体积小的文本文件（Markdown、TXT、HTML，单个不超过约 1 MB）连内容一起同步，在别的设备上打开时才取回来，最近的几篇会提前取回。
• 不同步什么：PDF 等大文件只同步书单，卡片上标着“仅书单”，内容不会过去；要带到另一台设备，请在原设备上用上面的“备份与恢复”。订阅里的文章不同步，各设备自己从订阅源读。
• 怎么保密：加密在你的浏览器里完成，同步服务只看到打乱的数据，读不了任何标题和内容；同步码只以哈希的形式保存。同步码就是钥匙：丢了就找不回来，别人拿到它就能读你的书架。
• 限制：免费空间约 9 MB，满了以后新文件只同步书单；半年（180 天）不用，同步空间会被清掉。两台设备同时改了同一处时，进度取较新的，书签合在一起，其它以正在使用的这台为准；一边删除、另一边改动的，改动保留。
• 关掉：“在这台设备上关闭同步”不会删除这里的任何内容；“删除云端数据”会清空同步空间，各设备上的内容都不动。

用得久了，页面会问你一次：如果以后加上“大文件同步”（PDF 等，空间更大），你愿意付费吗？你的回答只作为一个匿名计数发给同步服务，不含任何能认出你的信息。

写笔记：手机上像苹果备忘录

电脑上点顶栏的铅笔，手机上点右下角的圆形铅笔按钮（“添加”窗口里的“写一篇笔记”也行），打开一个整页的编辑器。

• 手机上：所见即所得。输入用的是手机自己的键盘、选字、听写和选区放大镜，第一行就是标题。键盘上方一排按钮：Aa（标题、小标题、正文、粗体、斜体、删除线、引用、编号）、待办（圆圈，点一下打勾）、列表、链接、图片、撤销、重做；点它们不会把键盘收起来。行首打 - 、1. 、#、[]、> 再按空格，会自动变成列表、编号、标题、待办、引用；在列表里回车接着写下一项，空的一项再回车就结束列表。
• 文字、链接和图片：贴文字只带文字（不带别处的颜色字体）；贴一个网址变成链接，贴图片的网址变成图片；也可以点“链接”“图片”输入地址（没写 https:// 会补上）。图片只是链接，不存图片文件，所以不占浏览器的空间，也不影响备份和同步；贴图片文件时会提醒改贴链接。
• 电脑上默认是 Markdown：左边写、右边实时预览，工具栏在上面；点 Aa（Markdown 工具栏最后一个）或 Aa 里的 MD 在两种方式之间切换，选择记在这个浏览器里。笔记里有表格、网页代码这类文档模式表示不了的写法时，会自动用 Markdown 打开，不会丢任何东西。
• 边写边存：停笔不到一秒就存进这个浏览器，不用点保存；写上 #标签 的词会成为这篇笔记的关键词；什么都没写就关掉，不会留下空笔记。
• 再改：卡片上的铅笔（手机上在“…”里）或阅读页顶栏的铅笔。返回键、Esc、“完成”都会先存再关。笔记和别的文件一样出现在书架里，能搜索、备份、同步。

合集：一批文件放在一起

一次导入的一批文件，可以放进一个合集。选中一个合集以后，卡片、分类、标签、搜索、“继续阅读”都只显示这个合集，书架就干净了。

• 切换：电脑上用页面上方的“合集”下拉框；手机上点左上角的目录按钮，左侧列表最上面就是合集。
• 管理：新建、改名、删除。删除合集会连里面的文件一起删，会先问你。
• 换合集：卡片上的“移到其他分类”里，可以把某个文件放进别的合集。

订阅：把别人的博客和文章源订阅进来

不知道订什么？左侧列表里的 “推荐订阅”（或网址后面加 #recommend）是站长挑的一百个左右的博客和栏目，分成科技、商业、读书、供应链、科学等类，每一类里流量大的在前。第一组“热榜与趋势”是各平台的热榜和热门社区：GitHub Trending、掘金、V2EX、B 站热门、网易云飙升榜、知乎、微博，以及 Hacker News、Product Hunt、Reddit、Lobsters，和金融、学术、音乐的头条。热榜订阅后，每次更新就是平台当前的榜单，每条带名次和热度，点开尽量在站内显示（见下）；这里只显示站点的服务实际提供的榜。想看所有榜（还有抖音、小红书、公众号、雪球、同花顺、Google 热搜、arXiv、微信读书的小说榜……），点公共目录左侧的“热榜”：先选一栏（综合热点、科技与开发、财经、国际、AI 与学术、读书与影音），再在旁边选平台；点开的内容尽量在站内显示：B 站、YouTube、网易云的视频和歌曲在窗口里用平台自己的播放器播放；新闻、博客、V2EX 的主题、知乎日报、GitHub 仓库的说明在阅读器里读；Apple 播客榜点开是节目和最新几集，点一集就在底部播放条里播；微博、抖音、知乎这类一句话的热搜显示成一张卡片（热度、平台给的摘要，再加这句话相关的新闻，每条都能在阅读器里读）。只有平台不让显示的（比如知乎的回答、公众号、QQ 音乐）才去原站，卡片最下面有“去原站看”。每个榜都能“订阅这个榜单”；公共目录“平台”标签里的热榜平台（知乎、微博、B 站、GitHub……）固定在那里，点开是它今天榜上的卡片，旁边有“看实时热榜”。勾“订阅”再点“订阅所选”，一次订好几个；勾“推送审核”再点“推送审核”，是把它们送去公共目录，由站长审核后收录。已经订阅的、已经在公共目录里的，会直接显示为已选。语言筛选和搜索框对它们同样有效。

想读的博客，不用每次去它的网站看有没有新文章：在“添加”窗口切到 订阅，把它订阅到你自己的书架里。

1. 点 添加，切到 订阅 标签。窗口下面的 “试试这些” 是站长挑的几个值得订阅的源，点一下就订阅，可以连着订几个，点“完成”回到书架。
2. 贴一个网址：博客首页、订阅源（RSS / Atom / JSON Feed）都行，点 查找。页面会告诉你它叫什么、最近有哪几篇。
3. 给这个订阅起个合集名，点 订阅。

• 文章都在这里读，不用跳走：订阅源自带全文的，最近几篇会把正文存下来（卡片上有“全文”标记）；订阅源只带摘要的，点开时由“更新服务”去读原文页面，提取正文后显示在阅读器里（有的页面要十几秒），并存在你的浏览器里，下次秒开；最新的几篇还会在空闲时提前读好。右上角和文末都有“阅读原文”。和你收藏的链接一样，可以搜索、加星、置顶、隐藏。在阅读设置里还能下载这一篇的网页（HTML），或者打印 / 存为 PDF。
• 读不了的页面：要登录或付费的、有“人机验证”的、靠脚本才显示正文的、PDF、对方在 robots.txt 里不让程序读取的，这里读不了。阅读器会告诉你原因，并给一个“打开原文”按钮；卡片上标着“仅原站”，以后点它直接在新标签页打开原文（一周后再试一次）。
• 什么时候更新：打开页面时自动更新（距上次超过 3 小时），也可以随时点“刷新”。网页没法在后台定时更新，所以不会主动推送；没有网络时看上次存下的。每个订阅保留最近 60 篇（你加了星或置顶的不会被清掉）。
• 今日听什么：侧栏里原来“音频”的位置。标题后面一行小字是“每日新歌/节目，喜欢不重样”；下面一行左边是“音乐 / 播客”开关，右边是排序和“卡片 / 列表”按钮；再下面是一条标签，当天的榜单和歌单在前（每日推荐、华语 / 欧美 / 韩流 / 日系热歌榜、Deezer 的 Top 100……；播客是各国的播客榜和“目录里的节目”），风格（摇滚、说唱、电子、爵士、古典、放松……）或播客分类（新闻、商业、故事、英语学习……）在后。手机上这条标签可以左右滑，在歌曲上左右滑动就换到下一个 / 上一个榜单。标签下面直接是歌曲或节目，默认是列表，每个榜单备有 200 项，一次显示 30 项，滚到快到底会自动再加 30 项；每行只写标题、来源（歌手或节目）、热度（榜单里的名次）和“试听”（只有试听片段才写）；点“播放全部”从第一首放起。整首的歌、整集的节目，以及“试听”（Deezer、Apple Music 公开的 30 秒片段，想听全曲点 ↗ 去平台）都进页面底部的播放条，点其中一首，榜单里它后面的接着放，放不了的自动跳过，授权名在“正在播放”页里；YouTube 的音乐视频在窗口里用 YouTube 自己的播放器看，在中国大陆通常打不开，标“海外”。内容会按界面语言排：系统是英文，推荐的就是欧美歌和英语播客榜；左下角可以点一下“中 / EN”换。发现页上还有一小块“今日听什么”，点“进入”去完整的页面。同一天所有人看到的一样，不记录你听了什么。
• 专注模式（学习、冥想）：点歌曲列表上的“专注”、播放条上的 ◎，或“正在播放”页里的“专注模式”，整个屏幕只剩一个缓慢变化的图案（呼吸 / 极光 / 暗，点一下换）和一行小字歌名，自动开始放整首的歌或整集的节目（30 秒试听不算）。按钮 4 秒不碰就隐去，动一下鼠标或碰一下屏幕再出来：上一首 / 暂停 / 下一首、音乐 ↔ 播客、定时（15 / 25 / 45 / 60 分钟，到点自动暂停）、换图案。Esc 或 × 退出，声音继续。读文章时，阅读栏上的“专注阅读”（手机在“Aa 阅读设置”里）收起所有按钮，只留正文和右下角一个小条（暂停、下一首、图案页、退出），进入时自动放，你在小条里暂停过，下次就不自动放。
• 播客：边听边读：订阅一个播客（贴它的 RSS 地址，和订阅博客一样），每一集的卡片上有“播客”标记和封面上的播放键。点那个键，或者直接点卡片的标题 / 封面，就开始播放，页面底部出现播放条：上一集 / 后退 15 秒 / 播放 / 前进 30 秒 / 下一集、进度条和时间、倍速、音量；点播放条上的封面打开“正在播放”页：节目说明、倍速（0.75× 到 2×）、定时关闭（15 / 30 / 60 分钟，或本集结束）、播放列表，一集放完自动放下一集。“推荐订阅”里的播客有“试听”按钮，不用订阅就能听最新一集。听的时候可以照常读文章、翻书架，声音不会断（别关这个页面）；手机锁屏和通知栏上也有播放控制（有的浏览器支持）。听到哪里会记下来，下次点播放接着听；这些只存在你的浏览器里。声音由节目自己的服务器直接送到你的浏览器，本站不经手、不保存；少数节目不让外站播放，放不了时会给你“打开原站”。
• 贴的是一篇文章（不是博客）：它没有可以跟着更新的源，只能存成一条链接，不会更新；能读的话，正文也一起存下来，在阅读器里读。
• 管理：合集的“管理”里可以刷新、“全部标为已读”、取消订阅（已存的文章一起清掉）。你删掉的某一篇，下次更新不会再出现。
• 换设备：在“管理”（或添加窗口的“导入 / 导出订阅清单”）里导出 OPML，或复制清单链接，到另一台设备上导入或打开那个链接。只同步订阅清单（一串网址），文章和已读状态各设备自己更新。OPML 也能和 Feedly 等阅读器互通。
• 隐私：别人的网站不让网页直接读，所以读取由本站的“更新服务”代劳：你订阅的网址、你点开的文章网址会发给它，它读完把标题、摘要和正文还给你的浏览器，自己什么都不保存。它读页面时不带你的任何 cookie、不登录，自报家门（用户代理写着“ZhiTreeBooks-Reader”），并遵守对方的 robots.txt。订阅清单只存在你的浏览器里。

5在手机上用

装到主屏幕，像 App 一样用

• Android（Chrome）：打开网站，点左侧栏最下面的“安装到主屏幕”，或浏览器菜单里的“安装应用 / 添加到主屏幕”。
• iPhone（Safari）：点底部的“分享”按钮 → “添加到主屏幕”。

装好以后全屏打开，打开过的页面和文件（最多 120 个）会保存下来，没有网络也能再读。

手机上的卡片和手势

• 卡片视图是两列：每张卡片留着封面、标题和一行信息，星标之外的按钮（置顶、隐藏、移动、公开、换封面、删除…）收在卡片上的“…”里，点一下展开，点别处收回。右上角的列表按钮可以切换成一列一条的列表。
• 读文章时左右滑：向左滑是下一篇，向右滑是上一篇（顺序就是书架当前的排序）；到头了会提示。顶栏没有“上一篇 / 下一篇”按钮了，目录面板里还留着一份，PDF 这类滑不动的文件用它。往左右滑动的代码块和表格不会被误翻页；选中了文字、放大了页面、从屏幕最边上起手（那是系统的返回手势）都不会翻页。
• 书架上左右滑：向右滑打开左侧列表，向左滑收起（在列表里的一条上向左滑，是露出它的按钮，见下面）。

左侧目录：合集、分类、左滑删除

点左上角的 ≡（或在书架上向右滑）打开左侧列表：最上面是合集，然后是分类、标签，最下面是“卡片目录”。把目录里的某一条往左滑，下面露出按钮：

• 红色“删除”：你自己的文件，点了会先确认。
• 灰色“隐藏”：站点上的书（你删不了），只在你的浏览器里隐藏。在“已隐藏”里则是“恢复”。
• 竖着滑还是滚动列表；滑出来以后点一下别处就收回去。

把别的 App 里的文件“分享到知树阅读”（Android）

装到主屏幕以后，在文件管理器、微信、浏览器里点“分享”，选“知树阅读”：分享的 PDF / Markdown / TXT / HTML 会打开“添加”窗口，选好合集点保存；分享的网址会直接存成“收藏的链接”。第一次装完，要等浏览器更新应用信息（通常一天内，重新添加图标会立刻生效）才会出现在分享列表里。iPhone 的 Safari 没有这个功能，请用“添加”多选文件。

6公共目录与投稿

点左侧的“公共目录”，看到的是很多人的博客、文章、GitHub 仓库、视频汇成的一份目录。它不存别人的全文：只记标题、摘要、封面图地址和回到原站的链接。点一篇文章，会在阅读器里直接读（和订阅里的一样，由“更新服务”读原文；读不了的页面、视频和仓库去原站）；你收藏它，读过的正文也一起存进你的书架。

• 两层：公共目录先是发现页：没有工具栏、没有标签和书架列表，只有今天值得看的内容、一行栏目入口和一个“全部来源 · 平台 · 标签 ›”按钮。点一个栏目、搜索，或点那个按钮，进入整个目录；侧栏里“发现”和“全部 / 文章 / 音频 …”并排：点“发现”回来，点“全部”或某个类型看整个目录里的那一类。
• 整个目录的顶部：标题下面是“栏目 / 平台”两排标签（太多就自动换行，不用左右滑；手机上只显示两排，其余在“更多”后面）。栏目一侧是 8 个栏目：今日摸鱼、AI 与科技、学习与研究、财经与商业（供应链在里面）、职场与产品、视频与创作者、读书与深度、全球正在发生（有内容的才显示）。一篇内容只属于一个栏目，点进栏目后下面一行是它里面的领域（比如“AI 与科技”里有 科技 / 编程），所以点不同的栏目，看到的是不同的文章；平台一侧是知乎、微博、微信公众号、B 站、YouTube、GitHub 等所有有节目的平台（名字最多 7 个字，长的会截短；先是按网址认出来的固定平台，再是动态的：每个独立网站自己算一个平台，当前最忙的 5 个先显示，其余在“更多 N ▾”后面，读者贴来的链接归“其他”）。两侧都有一个下拉按钮：平台一侧是“节目”，点开会列出这个平台下的每一个订阅节目，可以搜索、多选，勾选后切换平台就只看这些节目；栏目一侧是“栏目”，列出有文章的栏目（每行写着篇数），同样可以搜索、多选，勾选后栏目一侧就只看这些栏目里的文章。勾选保存在你的浏览器里，点标题下的“已选 N 个 ✕”一下清除。
• 第一次来，先问你一句“现在想看什么？”：四种心情（摸鱼一下、学习进阶、看懂热点、深度收藏），点一个就替你勾上对应的栏目；也可以自己点几个栏目再点“看这几个栏目”；“先随便看看”就不再问。只有你主动点了才会记下，页面不会替你猜，之后随时能在“栏目”下拉里改。勾选了栏目以后，首页就是你自己的首页：每个勾选的栏目一小节（3 张卡加“更多 ›”）。隔了 30 天以上再来，今日之后多一节“你可能错过了”；读过东西以后还有“最近读过”。进了栏目、领域或平台，标题下有一行“你在哪”（栏目：AI 与科技 ✕ ……），点侧栏的“发现”一下清掉全部筛选。
• 首页像一份“今天值得看”：今日 3 件值得看（一张大图卡加两张小卡，每天换一批，读过的不再出现）→ 编辑精选（读过东西以后叫“为你精选”；图文卡，小红书的样子，排成整齐的网格：最多 3 列，手机 2 列，封面一样大，同一行等高；每个领域或平台挑几条混在一起；你在这个浏览器里看过、收藏、订阅、点过喜欢的内容多了，会按你的兴趣排序，数据不离开你的设备，可以一键清除；“换一批”换下一组）→ 值得订阅（站长推荐和最近最热的节目，已经订阅的不再出现）→ 最新更新（同样的网格，上面出现过的不再重复）。右上角的“卡片 / 列表”按钮在哪里都有效（手机上也有）：点一下，所有的卡片变成一行一条的列表（小封面、标题、两行摘要、数字），再点回来。第一次来时，最上面还有一行“打开使用指南”的提示，点它去读指南，点 × 就不再出现。手机上首屏是一张大卡和两条，下面是两列的网格。
• 一张卡：封面、标题、摘要、标签、来源和日期，最下面一行是 ♥ 喜欢数（点一下就喜欢，再点取消）、👁 阅读数、🔥 热度和收藏书签。每张卡最多一个“为什么值得看”的小标签（热榜第 N 名、本周热读、因为你常看某个节目、N 人喜欢、N 次阅读、站长推荐、你订阅的；没有就不写）；文章不再标“文章”，语言只在和页面语言不同时才标（EN / 中文），日期显示“今天 / 昨天 / 10-22”。没有封面图的文章，封面上写着摘要的开头（像一张文字海报，以节目的颜色做底），热榜的名次是封面上的大数字。阅读目录里的文章时，页面底部还有喜欢 / 不喜欢两个按钮。
• 排序：最新发布、热度、最近阅读（只记在你的浏览器里）、标题。卡片上有热度（小火苗）。
• 热度从哪来：匿名计数——一条被打开、被喜欢、被收藏、被订阅，就给这一条记一次（同一个人同一条一天最多一次），不记是谁、不用 Cookie；浏览器开了“请勿跟踪”就什么也不发。
• 收藏：卡片上的书签按钮，把这条链接存进你自己的书架（只存在你的浏览器里），标着“收藏的链接”。
• 订阅：在公共目录里点“订阅”，订阅的是整个目录、某个类型、某个标签或某个书架。
• 推荐一个博客：贴它的网址（博客首页或 RSS 都行）去“收录”。订阅源也可以送审，站长审核通过后，它的新文章每天自动进入目录。

把自己的内容送进去：三种方式，都不需要账号

1. 贴一个网址：博客、文章、视频、GitHub 仓库、PDF 都可以。先点“检查”，页面会告诉你它是什么、读到几篇、最近几条是什么，也会先拦下“目录里已经有了”的重复项。确认后勾选“我有权发布这些内容”，点“提交”。只想自己读、不想公开？同一个网址也可以直接订阅到你的书架，不用审核：窗口里点“改为订阅这个网址”（检查出来是订阅源时，结果里也有“订阅到我的书架”），会带着这个网址跳到“添加 → 订阅”。
2. 写文章：在窗口里切到“写文章”，写或粘贴一篇 Markdown，署你填的作者名。通过后由目录托管成一个页面（公开可见、不显示图片），可以随时要求下架。
3. 点卡片上的地球图标：“我的书架”里每张卡片都有。有网址的，送这个网址；你电脑或浏览器里的 Markdown / TXT，送文章正文；书、PDF、网页小工具这类没有网址的，只公开一张书籍卡片（标题、作者、摘要、标签；可以选“一本书 / 书单 / 在线书籍 / 小说”），不含文件。

提交以后会进入站长的审核队列，卡片上显示“已提交，等待审核”；通过后就出现在公共目录里。网址的不同写法（http / https、www、末尾斜杠、跟踪参数）算同一个；标题、作者、摘要几乎一样的也会被拦下，并告诉你像哪一个。

7订阅本站（RSS）

这一节讲的是反过来：订阅这个网站，用你自己的 RSS 阅读器读。（订阅别人的文章，见第 4 节。）点顶栏绿色的“订阅”按钮：里面有“在 Feedly / Inoreader 中订阅”的一键链接和复制按钮。可以只订阅一部分：全部、某个分类、某个标签，打开时默认选中你正在看的那个。订阅以后，有新文章时你的 RSS 阅读器（Feedly、Inoreader 等）会提醒你。

8常见问题

想自己搭一个这样的网站？切到“安装部署”。

• 需要什么
• 本地跑起来
• 放内容
• 置顶这篇说明
• 部署到 Vercel
• 让搜索引擎找到
• 开通公共目录
• 审核页
• 疑难

0你需要什么

这个项目是一个文件夹：index.html（网页）、serve.py（本地服务）、build_index.py 和 seo.py（部署时构建）、vercel.json（部署设置），以及你的内容所在的 library/。

1在自己电脑上跑起来

在项目文件夹里打开终端，运行：

python serve.py

Mac / Linux 用 python3 serve.py。浏览器会自动打开 http://127.0.0.1:8000，换端口用 --port 9000。就这一条命令，不用装别的。

• 往 library/ 里放文件，刷新页面就出现；也可以点“添加”或把文件拖进页面，直接写进 library/。
• 这时页面是“站长模式”：卡片上的移动、删除、置顶、星标、隐藏都会真的改文件（星标、置顶、隐藏、改标题保存在 library/_meta.json）。
• 服务只接受发往本机的请求；它能写文件，不要把它暴露到公网。改了 serve.py 之后要重启它。

2往书架里放内容

library/
├── books/      书籍
├── tools/      工具（网页小程序）
├── notes/      个人笔记
├── featured/   精选
└── _meta.json  星标、置顶、隐藏、标题改动（自动生成）

• 一级文件夹就是分类，新建别的文件夹会自动成为新分类。
• 工具 = 文件夹：一个网页工具由 index.html + css + js + 图片组成时，放进 library/tools/工具名/，整个文件夹是一张卡片，里面的资源请用相对路径（style.css），不要用 / 开头。这份指南本身就是这样放的：library/notes/guide/。
• 支持 HTML、Markdown、TXT、PDF，单个文件上限 80 MB。Word（.docx）请另存为 PDF 或 Markdown。

Markdown 开头可以写 front matter，指定标题、摘要、关键词；HTML 里用 meta：

---
title: 我的标题
description: 一句话摘要
tags: [供应链, 读书]
featured: true     # 设为精选
pinned: true       # 置顶，所有访客都看到
---

<meta name="description" content="一句话摘要">
<meta name="keywords" content="供应链, 采购">
<meta name="archive:pinned" content="true">

同一篇的另一种语言

如果一篇内容有两种语言的页面，各放一个文件，再告诉网站英文那份在哪里。访客把界面切到英文时，看到的是英文标题和摘要，点开的是英文页；搜索引擎会拿到两个地址，并知道它们互为译文。

---
title: 我的标题
title_en: My title
description_en: A one-sentence summary in English
tags_en: [supply chain, reading]
alt_en: en/index.html     # 英文页，相对于这一篇的位置，必须在 library/ 里
---

<meta name="archive:title_en" content="My title">
<meta name="archive:description_en" content="A one-sentence summary in English">
<meta name="archive:keywords_en" content="supply chain, reading">
<meta name="archive:alt_en" content="en/index.html">

这份指南就是这样做的：library/notes/guide/index.html 是中文页，library/notes/guide/en/index.html 是英文页。

3让这篇说明排在第一位

想让所有访客都先看到这篇指南，需要你在自己电脑上置顶，再重新部署。两种做法，选一种：

1. 在文档里写（最省事）：Markdown 的 front matter 里加 pinned: true，HTML 里加 <meta name="archive:pinned" content="true">。写成数字（比如 pinned: 2）也行，数字越大越靠前。这份指南用的就是这种。
2. 在页面上点图钉：用 python serve.py 打开页面，点卡片上的图钉（写进 library/_meta.json）。

然后重新部署（见下一节）。多篇置顶时，最后置顶的排最前。

4部署到 Vercel

Vercel 是静态 / 无服务器平台，不能运行 serve.py。部署时它会按 vercel.json 先运行构建脚本，把站点构建到 dist/，部署的是 dist/，不是你的原文件夹。

1. 安装 Node.js，然后安装 Vercel 命令行并登录：

   npm i -g vercel
   vercel login

2. 在项目文件夹里运行 vercel，按提示创建项目（第一次回答几个问题，一路回车即可）。
3. 打开 vercel.json，把构建命令里的网址 --site-url https://books.zhitree.cn 换成你自己的（站点地图和订阅源都用它）。
4. 正式发布：

   vercel --prod

5. 想用自己的域名：Vercel 项目的 Settings → Domains 里添加并按提示设置解析。

• 之后每次更新：往 library/ 里放好 → 本地用 serve.py 看一眼 → vercel --prod。新文件必须重新部署才会出现。
• 隐藏的内容不会上线：dist/ 里没有隐藏的文件，清单里也没有；想让某篇上线就取消隐藏。
• 线上的书架对所有访客只读：访客不能往服务器里添加、移动、删除。
• 看不到新内容时，打开 https://你的域名/manifest.json，看 generated 和 items：不在清单里，就是部署的不是最新文件。
• 本地预览请用 serve.py，不要用 vercel dev（它启动时就记住了当时有哪些文件，之后新增或移动的文件会 404）。

署名、联系方式、隐私与条款

about.html、privacy.html、terms.html 是普通 HTML，直接改文字。署名和联系方式写在 site.json（不会发布）：

{ "owner": "你的名字或昵称", "contact": "you@example.com", "license": "CC BY-NC 4.0" }

5让搜索引擎找到你

部署时会自动做这些，你的原文件一个字节都不会改：给每个页面补上缺的标签、给 Markdown / TXT 生成带全文的页面、生成 sitemap.xml 和 robots.txt、把长长的中文文件名换成短而稳定的地址、生成订阅源。有英文版的页面还会互相补上 hreflang 链接，并一起写进站点地图，让搜索引擎把对应语言的页面给对应语言的读者。你要做的只有两步：

1. Google Search Console：添加你的网址并验证，在“站点地图”里提交 sitemap.xml。刚提交时显示“无法获取”很常见，过几小时到两天才会变成“成功”。
2. Bing Webmaster Tools：可以直接“从 Google Search Console 导入”；或者提交同一个 sitemap.xml。

想把新地址主动告诉 Bing 等（IndexNow）：

python indexnow.py --init          # 只需第一次：生成密钥，写进 site.json
vercel --prod
python indexnow.py                 # 之后每次部署完运行，只发新的和改过的地址

6开通公共目录和投稿（可选）

公共目录的数据和程序在另一个项目 shelf-directory（和本项目同级的文件夹），由 GitHub 每天自动更新，本站只负责显示。分三步：

1. 放到 GitHub 上：新建一个公开仓库，把 shelf-directory 推上去；仓库 Settings → Actions → General → Workflow permissions 选“Read and write”；到 Actions → Daily → Run workflow 手动跑一次。
2. 让本站显示它：在 site.json 里加上 "directory": "目录的网址"（以 / 结尾），重新部署。页面左侧就出现“我的书架 | 公共目录”。
3. 让访客不用 GitHub 账号就能提交：把 shelf-directory 也部署成一个 Vercel 项目（里面的 api/submit.py 就是提交服务），并设置环境变量：

   名字	值
   SHELF_REPO	用户名/仓库名
   SUBMIT_GITHUB_TOKEN	只给这个仓库的 Issues 读写（再加 Contents 只读）的令牌
   ALLOWED_ORIGINS	允许提交的网页来源，默认你的主站网址
   IP_SALT	一长串随机文字，用来给来访者地址做不可逆的短哈希，限制每人每天的提交次数

   把提交服务的地址（https://…/api/submit）写进 shelf-directory/registry/config.json 的 "submit_api"，推送。改了环境变量要重新部署一次才生效。
4. 订阅功能自动跟着开通：同一个目录项目里的 api/feed.py 就是读者订阅别人博客时用的“更新服务”（网页自己读不了别人的网站，由它代读，只返回标题、摘要和链接，什么都不保存，也不需要任何环境变量）。页面把提交服务地址末尾的 /submit 换成 /feed 来找它，所以只要 submit_api 写对了、ALLOWED_ORIGINS 里有你的主站网址，“添加”窗口里就会出现“订阅”标签。每个访客每 10 分钟的查询次数有软限制，防止被滥用。
5. 同步（可选，需要一个 Redis）：同一个目录项目里的 api/sync.py 是“同步码”服务，读者的书单和小文本加密后存在一个 Redis 里（服务器读不了内容）。在 Vercel 项目的 Storage / Marketplace 里添加一个 Upstash Redis 并连到这个项目，它会自动写入环境变量（KV_REST_API_URL + KV_REST_API_TOKEN，或 UPSTASH_REDIS_REST_URL + UPSTASH_REDIS_REST_TOKEN，两种都认），重新部署一次即可；打开 https://你的目录站点/api/sync 看到 "configured": true 就开通了，页面左下角会出现“同步”按钮。可选环境变量：SYNC_QUOTA（每个同步码的字符数上限，默认 1200 万）、SYNC_TTL_DAYS（不使用多少天后清掉，默认 180）、SYNC_MAX_KEYS（数据库里的键超过多少就不再接收新的同步码，默认 6000，约 1000 个）。每个访客每天最多新建 3 个同步空间。GET /api/sync 还会显示“愿意付费吗”问题收到的匿名计数。

7审核页：输入密码就能管理

所有申请（GitHub 表单、网页上提交的网址、书架里的文章）都进同一个审核页：https://你的目录站点/admin/。

在目录项目的 Vercel 环境变量里再加两个，重新部署：

• 通过 / 拒绝只改仓库里的数据，不需要重新部署任何站点。已收录的内容和托管的文章也能在这里下架。
• 一次审很多个：每条申请前面有个勾（重复的、检查没通过的不能勾）。“通过所选”“拒绝所选…”处理你勾的；“选中检查通过的”帮你把机器人检查通过的都勾上；“一键通过全部检查通过的”不用勾，直接处理它们（疑似重复的不在其中，要你自己看一眼再勾）。一次最多 60 个，在 GitHub 的一次运行里处理完（通常 1–3 分钟），页面会跟着进度提示，没通过的会留在待审里并写明原因。批量推送了很多条之前，先在目录项目的环境变量里把 SUBMIT_PER_DAY 调大（默认每人每天 5 条）。
• 登录后浏览器拿到的是一个会过期的通行证（默认 8 小时，勾“记住”是 14 天），不是令牌。换密码或换令牌，所有已登录的设备都会立刻退出。
• 没配密码时，页面会回到“用 GitHub 令牌登录”，并告诉你服务器上缺的是什么。

8疑难

只是想用？回到“使用说明”。