Repository navigation
feat:Add local bookmarks and passage notes - #31
Open
xiaoshuaijie wants to merge 1 commit into
Open
xiaoshuaijie wants to merge 1 commit into
xiaoshuaijie wants to merge 1 commit into
Conversation
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
概述
本 PR 为 XRobot 文档站增加一层本地阅读能力:读者可以收藏整篇文章,也可以把正文中的一段文字存成便签。书签和便签都只保存在当前浏览器的
localStorage中,不引入账号、后端或新的埋点。背景与问题
文档以长文为主。目前读者想回到某篇文章或某段话,只能保留浏览器标签页,或者把文字复制到别处。缺少两种能力:
本 PR 用纯前端方案解决这两个问题,站点仍然保持静态部署,不增加服务端状态。
改动内容
1. 导航栏收藏当前文章
☆ 收藏/★ 已收藏,注册为自定义 NavbarItemcustom-bookmark。pagehide会静默更新阅读进度,书签页始终显示最新位置。2. 划选正文存为便签
.theme-doc-markdown内选中至少 4 个字符,选区上方浮出✎ 存为便签。mousedown会阻止默认行为,避免点击时浏览器清空选区。code、链接等元素时也能正常保存和回跳。3. 右侧「本页便签」面板
本页便签/Notes on this page。全部 ↗入口和便签列表。4.
/bookmarks书签页/en/bookmarks。5. 跳转恢复流程
sessionStorage写入一次性恢复标记,目标页读取后删除。indexOf命中后构造Range,滚动到视口中央。CSS.highlights闪烁高亮。6. 中英文与移动端
strings.ts按路由提供中英文文案,覆盖导航栏、侧栏、书签页、空态、按钮和状态提示。<li>,因此☆ 收藏和书签在汉堡菜单里也可用。7. 没有目录的文章也显示便签栏
Docusaurus 只在
toc.length > 0时渲染右侧目录列。仓库中有 6 篇文档没有任何##标题,便签面板会因此消失。本 PR 从 Docusaurus 3.9.2 复制并调整了
DocItem/Layout:只要没有显式设置hide_table_of_contents,桌面端就保留右栏;DocItem/TOC/Desktop在没有标题时省略空目录,只渲染便签面板。交互流程
数据模型
localStorage键:bookmarks:v1:{ [path]: Bookmark }notes:v1:{ [id]: Note }备份文件:
导入规则:
updatedAt更新的一方胜出。id去重,updatedAt更新的一方胜出。notes字段时仍然可以导入,只合并书签。文件说明
验证
构建
npm run build中英文均构建通过。/bookmarks.html与/en/bookmarks.html。浏览器手工验证
✎ 存为便签→ 右侧出现便签。★ 已收藏;刷新后状态保持。/bookmarks→ 正确显示文章分组、便签行和导入导出入口。/docs/intro,CSS.highlights.has('note-flash')为true。code→ 便签仍能准确定位。scrollY = 511 / 1022。localStorage→ 导入 → 书签和便签恢复。/en/docs/intro、/en/bookmarks均显示英文文案。☆ 收藏和书签,书签页布局正常。##标题的文档仍然显示便签面板。类型检查
npx tsc --noEmit没有新增错误。src/pages/index.tsx和src/pages/qq.tsx中的两个Layouttitle属性报错是本次改动之前就存在的。兼容性与风险
DocItem/Layout是不安全 swizzle,升级 Docusaurus 时需要重点复查。[...map.values()]宽松编译成[].concat(iterator),因此代码里统一使用Array.from处理 Map 迭代器。innerHTML,没有 HTML 注入风险。localStorage容量限制;单条摘录截断到 240 字,正常使用不会达到上限。不在本次范围
Checklist
zh+en)