README file from
Github格间日记(Grid Diary)
Obsidian 里的九宫格日记插件。灵感来自九宫格 / 曼陀罗日记与《晨间日记的奇迹》: 每个格子放一句问题当引导,写起来不费劲。
数据全部是普通的 Markdown 文件,不锁定、不加密、随时可以拔走。
一、它是什么
一天一个 Markdown 文件,文件里每个 ## 二级标题 就是一个「格子」:
# 2026-11-08
## 今日事件
今天去看了展览。
## 今日新知
Markdown 里的空行就是分段。
## 今日碎记
随手记一条。
<!-- gd-layout {"v":3,"cols":2,"skin":"magazine","border":"none","cover":"attachments/a.png","cells":[...]} -->
插件把 ## 今日事件 这类标题渲染成九宫格卡片,正文一个字都不改。
不写插件也能正常读,装了插件只是换个看法。
二、主要能力
1. 九宫格
- 每格右上角一个
+:在下方 / 右侧加一格、插入图片、插入动图、插入贴纸、插入片段、删除这一格。 - 空格子显示引导问句(晨间 / 日间 / 夜间三套),写着写着就有话说了。
- 打字时格子微微抬起,有手感。
- 就地编辑,点外面自动保存。
- 格式栏:粗体、斜体、删除线、高亮、颜色、图片、动图、附件。
- 格子可以拖拽排序、拖右下角改大小、设强调色。
2. 三种排布
- 上下滚(默认)
- 左右滚
- 左右翻页(带页码和「全宽」按钮)
格子宽度、每屏几列、每行几行都能调。
3. 页面外观
- 六种风格:现代卡片 / 手账纸感 / 杂志留白 / 便当格 / 极简黑白 / 自定义。
- 四种格子边框:无 / 细线 / 双线 / 虚线。
- 背景按块独立,互不串台(v3.23 起的核心):主页中间背景 / 主页格子 / 目录上层区 / 目录下层区 / 日历 / 日历格子 / 灵感 / 流线图,每一块都有自己的一份背景配置;改一块不会连带动别的。
- 文字配色只留三项:每一处只保留「字色 / 线色 / 强调色」,留空即跟全局;字族、字号、行高、首行缩进统一在「主题」里管一套,避免两处来源打架。
- 照片墙(仅主页):默认 12 张,可继续加图;每张可拖、可四角缩放;视频可缩成右侧小窗与照片并排。
- 封面:可换图、可拖动取景、可拖高度(60–1200px)、可设兜底图。
- 贴纸:天气 / 心情 / 标签三组,整篇最多 5 个,单格 1 个。
- 统一选图器:预览 + 六种快捷裁剪(居中裁剪 / 填充 / 适应 / 拉伸 / 平铺 / 原图)+ 手动框选,只存坐标不剪原图。
- 从系统 / 从库 / 贴链接 / 下载网络图,四条来源都通
- 库里选图支持视频,带「全部 / 图片 / 视频」筛选和格式角标(PNG / JPG / MP4…)
4. 图层舞台
封面区是一个可以一层层往上叠的舞台:
- 背景层、照片层、座右铭层、标志层
- 每层可以是纯色、渐变、图片、动图、视频
- 每层能拖、能缩、能调透明度、能设叠加方式
- 层数不设上限
5. 图片与视频
- 支持
png / jpg / jpeg / webp / svg / bmp / avif - 动图
gif / webp / apng直接播放 - 视频
mp4 / webm / ogv / mov当壁纸(静音循环,需要手动打开开关) - 轮播壁纸:选一组图,按每次打开换或定时换
- 库里选图已支持视频:面板顶部有「全部 / 图片 / 视频」切换,视频带 ▶ 标记与 MP4/WEBM 角标
v3.23 起移除了「底图按日 / 按周 / 按月自动换色」那一整套槽位。它和多处背景配置写的是同一批 CSS 变量,是背景串台的根源。现在一个位置就是一份固定背景,想换什么直接改就行。
6. 日历
- 五种骨架:月网格 / 周条 / 纵向年历 / 大日期 / 双栏月历(外加双月并排)
- 六种纹理:无 / 方格纸 / 点点阵 / 细横线 / 纸纹 / 渐变
- 底图两种摆法:
- 顶部横幅(推荐):图片独占顶端一条,日历整体排在它下面,两者不会重叠;横幅高度 60–360px 可调,日历跟着自动让位
- 整块铺满:图片当整页背景,日历浮在上面,自动压一层蒙层保证数字看得清
- 图片位置随便调:设置里点「裁剪 / 调位置…」,拖动选区就换取景;裁剪框的宽高比会跟着当前摆法走(横幅按横幅比例、铺满按整页比例),拖完就是所见即所得
- 内置农历:1900–2100 的农历、节气、节日,运行时零依赖
- 点日期先出预览卡(不跳转),双击才进。已经写过的那天会问「再写一篇 / 打开已有」
- 可折叠成一条细边,点开还原;四角可拖
- 可以放在标签页,也可以做悬浮窗
7. 目录
- 搜索框 + 「文件夹」三个字(点开是菜单)
- 上下双面板:上面文件夹树,下面该文件夹的笔记
- 上下两区背景独立:上区(文件夹)和下区(文件)各有一份背景与磨砂,改一块不影响另一块;两区各自的行背景也能单独设
- 每条笔记前面一个小图钉(取当天的图或封面)
- 今天 / 昨天 / 前七天 / 更早 自动分组
- 文件夹图标三种来源:内置线体图标 / 表情 / 图片(库里选,或直接粘网址)
- 第二层「图片」:一个文件夹一张,只存引用不复制原图
- 移动模式:点一下进入,文件夹前出现拖拽手柄,再点一次退出
- 拖拽移动、右键移动到…、紧凑模式、隐藏名单、篇数与字数
8. 流线图
- 竖轴贴左、卡片占满整宽的单列排法
- 按年分段,点任意一行直接开这一天的浮窗
- 显示缩略图、字数、改过几次
- 版本回退:列出当天所有历史版本(时间、字数、改动),点一下回到那一版
- 配色跟随主题(强调色 / 字色 / 线色 / 底色 / 卡片底色),不再用一套写死的旧色
- 可放右侧栏,也可做浮窗
v3.23 起移除了卡片左边那三条「新增绿 / 修改橙 / 删除红」色条 —— 那是语义色、不跟主题走,也是之前一直关不掉的橙色边框来源。
9. 悬浮窗
灵感笔记(Ctrl+Shift+G 唤起)有两种模式,标题栏一键切换:
- 格子模式
▦:跟主页当天那篇九宫格日记联动,改一格就是改日记 - 普通笔记
✎:直接编辑任意一篇 Markdown,不进格子、不需要模板、不跟日期绑。- 「+新」按时间戳新建一篇,放哪由你定(默认
灵感/) - 「挑」从库里选任意现有笔记接着写
- 想记什么记什么,纯粹当记事本用
- 「+新」按时间戳新建一篇,放哪由你定(默认
- 输入保护:正在打字时不会被自动保存打断,光标不跳、内容不会丢(格子模式和普通笔记模式是同一套保护)
- 打字时不再被自动保存打断;背景只留图片与透明度两项
- 日历浮窗:纯色底、可调透明度与磨砂、可拖可缩放
- 流线图浮窗:可多开,位置会记住
10. 主题系统
一个主题管全部视觉,存在 vault 的 主题/ 文件夹里,是普通 JSON,可以备份、可以回滚。
- 七组参数:底色 / 字体 / 线体 / 图标 / 格子 / 排版 / 动效
- 六套预设:宣纸 / 极简白 / 夜航 / 手账 / 杂志 / 便当
- 每个主题带版本号和改动记录,能回滚到任意一版
- 切换项目时视觉可以一起换
11. 正文排版
按纸书的规矩来:
- 首行缩进 2em(可调 0–4)
- 段落间距 0.8em(可调 0–2)
- 标题下方间距 0.5em(可调 0–1.5)
- 标题、列表、引用、表格不受缩进影响
12. 粘贴与模板
- 粘贴自动识别:标题 / 表格 / 分隔符 / 空行分段
- 同名标题自动合并,不会被切成「片段 1、片段 2」
- 按当前模板对齐,模板里没写的格子留空
- 格式过滤、关键词过滤
- 模板分六类:主页 / 目录 / 日历 / 悬浮窗 / 格子 / 表格
- 可以只存标题,也可以连内容一起存
13. 历史
- 每次改动前自动留快照
- 按天查看、对比、一键回退
- 恢复删除
三、更新日志
见 CHANGELOG.md。当前版本 v3.24.1,这一轮主要做了三件事:
v3.23 —— 背景串台、按色结构
- 删掉「除目录以外」的按色结构:按日 / 按周 / 按月换色整套移除,流线图的改动色条也一并删掉
- 背景收口到一处出口,不再有多套配置抢写同一批 CSS 变量
- 分区:目录拆成上区 / 下区;主页拆「中间背景 / 格子」;日历补上格子背景(之前选择器写错,从来没生效过)
- 文字:每处只留字色 / 线色 / 强调色,其余统一归全局
- 灵感浮窗新增「普通笔记」模式
v3.24 —— 日历底图
- 底图收成两种摆法:顶部横幅(图片与日历不重叠,横幅高度可调)、整页铺满
- 图片位置在裁剪框里拖选区即可调整,框的比例跟着当前摆法走
v3.24.1 —— 输入跳转修复
- 普通笔记模式套上跟格子模式同一套保护:保存中、或光标在编辑框里,一律不重建;外观改动只重绘外壳不动正文。之前打字会被自动保存打断,就是漏了这层
四、安装
手动安装
- 下载 Release 里的
main.js、manifest.json、styles.css - 放进
<你的库>/.obsidian/plugins/grid-diary/ - 重启 Obsidian → 设置 → 第三方插件 → 找到「Grid Diary」→ 开启
从源码构建
git clone https://github.com/3388038686-oss/obsidian-gezhi-diary.git
cd obsidian-gezhi-diary
node build.mjs # 生成 dist/main.js
构建脚本零依赖,只需要 Node。它会把 src/ 下按 NN-名字.js 命名的分片按序拼起来,做一次语法校验,再输出到 dist/。
测试
node test.mjs # 纯逻辑(解析、迁移、模板、粘贴、裁剪换算)
node smoke.mjs # 插件级(加载、视图注册、命令)
node domsmoke.mjs # 渲染级(真跑 dist/main.js,用假 DOM 断言元素)
五、目录结构
src/
00-header.js 依赖解构
01-constants.js 常量、默认设置、工具函数
02-lunar.js 农历 / 节气 / 节日(静态表)
02-parser.js Markdown ↔ 格子,layout 读写,粘贴解析
03-history.js 快照与撤销
04-crop.js 裁剪对话框
04-image-picker.js 统一选图器(预览 + 六种快捷裁剪)
04-modals.js 各种弹窗
04-theme.js 主题管理器
05-stage.js 图层舞台 + 照片墙
05-view-grid.js 九宫格主视图
06-float.js 灵感笔记浮窗
06-view-sidebar.js 目录
07-calendar-panel.js 日历面板
07-calendar.js 日历视图外壳
07-view-timeline.js 流线图
08-settings.js 设置页
08-view-table.js 表格视图
09-plugin.js 插件主体、命令、生命周期
99-footer.js 导出
六、数据格式
每个日记文件末尾有一行注释保存布局,正文完全不受影响:
<!-- gd-layout {"v":3,"cols":2,"skin":"magazine","border":"none",
"cover":"attachments/a.png","coverHeight":160,
"coverPos":"50% 50%","crops":{"cover":{"x":0,"y":0,"w":80,"h":100}},
"layers":{...},"cells":[{"cs":1,"rs":1,"h":0,"accent":"","collapsed":false}]} -->
v:3是当前版本,老文件(v1 / v2)能读,只有你改过才会升级写回crops存裁剪框,是原图百分比,不剪原图- 删掉这行注释也不影响阅读,只是会丢掉布局
七、许可
MIT