PaperCraft

PaperCraft

A customizable manuscript paper plugin for Obsidian — give your notes the warmth and beauty of traditional manuscript paper.

PaperCraft brings the warmth of traditional manuscript paper into Obsidian with an intuitive visual panel — what you see is what you get. No CSS knowledge required. Customize paper textures, line patterns, colors, typography, and drawing annotations through a beautiful, interactive UI.

English Description

PaperCraft is an Obsidian plugin that customizes your note appearance with traditional manuscript paper styles. It provides:

• 16 handcrafted templates — including horizontal lines, vertical lines, grid, dot grid, and more
• Real-time visual editor — see changes instantly as you adjust parameters
• Multiple paper textures — kraft paper, xuan paper (rice paper), concrete, linen
• Flexible line patterns — horizontal, vertical, grid, dot grid with adjustable spacing and color
• Chinese typography optimization — 35+ Chinese font presets, customizable line-height, letter-spacing, margins
• CSS import — auto-parse any .css file into visual parameters
• Drawing annotation — SVG drawing layer for handwritten notes

为 Obsidian 打造的稿纸客制化插件

让笔记拥有传统稿纸的质感与美感。可视化操作，所见即所得，不需要 CSS 知识。

PaperCraft 把传统稿纸的温润质感搬进 Obsidian，用直观的可视化面板替代 CSS 代码——所见即所得，一目了然。

---

---

Why PaperCraft?

Writing for a long time? Tired of staring at white editors? CSS snippets feel too technical? PaperCraft brings the warmth of traditional manuscript paper into Obsidian with an intuitive visual panel — what you see is what you get.

Comparison with CSS Tools

Simply put: Professional manuscript effects without writing a single line of CSS.

---

为什么选择 PaperCraft？

写过文章的人都知道：白色的编辑器看久了眼睛累，纯 CSS 代码又太劝退。 PaperCraft 把传统稿纸的温润质感搬进 Obsidian，用直观的可视化面板替代 CSS 代码——所见即所得，一目了然。

与其他 CSS 工具的区别

简单来说：不需要写一行 CSS 代码，就能得到专业级的稿纸效果。

---

核心特色

16 套文艺模板，一键切换

内置 16 套精心设计的模板，涵盖横线、竖线、点阵等多种风格，每套都配有专属配色和字体方案：

• 月白 —— 淡蓝底 + 横线 + 楷体，清雅如月光
• 星点 —— 米白底 + 点阵 + 楷体，简约而不简单
• 薄荷碎影 —— 薄荷绿底 + 横线 + 雅黑，清爽护眼
• 旧卷星砂 —— 仿古黄底 + 点阵 + 宋体，古朴典雅
• 玫瑰落英 —— 暖白底 + 点阵 + 楷体，温柔浪漫
• 晴空碎玉 —— 淡蓝底 + 点阵 + 苹方，通透如晴空
• 豆沙清梦 —— 豆沙绿底 + 横线 + 仿宋，经典护眼
• 素笺白露 —— 纯白底 + 点阵 + 雅黑，极简主义
• 墨蓝横线 —— 冷白底 + 横线 + 宋体，沉稳大气
• 淡紫微雨 —— 淡紫底 + 点阵 + 楷体，梦幻雅致
• 古风遗韵 —— 仿古黄底 + 竖线 + 宋体，古意盎然
• 桃花拾遗 —— 桃花粉底 + 点阵 + 仿宋，少女心满满
• ……以及更多

中文排版深度适配

PaperCraft 从第一天就为中文写作而设计：

• 35+ 款中文字体预设：宋体、仿宋、楷体、微软雅黑、思源宋体、苹方、华文行楷、隶书……覆盖主流中文字体生态
• 字间距精细调节：中文排版最讲究字间距，0-0.5em 无级调节
• 行高独立控制：1.0-3.0 行高范围，适配不同阅读场景
• 页面四向边距：上/下/左/右边距独立设置，还原稿纸的留白美学

可视化设置面板

告别 CSS 代码，用标签导航管理所有参数：

• 纸张质感 —— 牛皮纸 / 宣纸 / 混凝土 / 亚麻 4 种纹理，透明度和缩放可调
• 条纹图案 —— 横线 / 竖线 / 方格 / 点阵 4 种图案，间距、粗细、颜色全可控
• 颜色配色 —— 纸张底色 + 文字颜色，颜色选择器即点即变
• 字体排版 —— 字体、字号、字间距、行高，所有参数实时预览

实时预览，所见即所得

设置面板顶部有独立的实时预览区。调整任何参数，预览区立刻同步变化。满意后再点击「应用到笔记」，不影响正在编辑的内容。

CSS 导入：从代码到可视化

已有 CSS Snippet？PaperCraft 支持导入 .css 文件，自动解析其中的背景色、字体、行高、间距等属性，转换为可视化参数继续调整。从代码到可视化，无缝衔接。

---

安装

方法一：直接安装

1. 下载 main.js、manifest.json、styles.css 三个文件
2. 在你的 Obsidian Vault 中创建 .obsidian/plugins/papercraft/ 目录
3. 将三个文件放入该目录
4. 打开 Obsidian → 设置 → 第三方插件 → 找到 PaperCraft → 启用

方法二：从源码构建

git clone https://github.com/gibsonchan-5/PaperCraft.git
cd PaperCraft
npm install
npm run build

构建产物 main.js 会生成在项目根目录。

---

使用指南

快速开始

1. 启用插件后，左侧 Ribbon 栏会出现稿纸图标，点击打开侧边栏
2. 侧边栏展示所有模板，点击任意模板即可应用
3. 点击侧边栏 ⚙ 图标进入设置面板进行精细调整

侧边栏操作

• 模板网格：点击卡片切换模板，选中状态有高亮边框
• ↺ 清除格式：一键重置当前笔记的所有稿纸样式
• ⚙ 设置：打开可视化设置面板

设置面板

设置面板分为四个区域：

1. 实时预览区（顶部）—— 调整参数时实时变化，点击「应用到笔记」才生效
2. 标签导航（纸张质感 / 条纹图案 / 颜色配色 / 字体排版）—— 分类管理所有参数
3. 操作按钮（底部）—— 四个竖向排列的按钮：
   • 应用到笔记：将预览区的样式应用到当前笔记
   • 保存为新模板：将当前参数保存为自定义模板，可命名
   • 导入 CSS：从 .css 文件导入样式，自动解析为可视化参数
   • 重置预览：将预览区恢复为默认值（不影响已应用的笔记）

---

项目结构

papercraft/
├── main.js                      # 编译产物（直接安装用）
├── main.ts                      # 插件主入口
├── manifest.json                # Obsidian 插件清单
├── styles.css                   # 插件 UI 样式
├── esbuild.config.mjs           # 构建脚本
├── tsconfig.json                # TypeScript 配置
├── package.json                 # 项目配置
└── src/
    ├── data/
    │   ├── PaperData.ts         # 数据类型定义
    │   └── Defaults.ts          # 默认值与防御性加载
    ├── engine/
    │   ├── CSSGenerator.ts      # CSS 生成引擎（BackgroundLayer 层管理）
    │   └── ThemeApplier.ts      # 样式注入与移除
    ├── settings/
    │   └── SettingsTab.ts       # 可视化设置面板（标签导航 + 实时预览）
    ├── sidebar/
    │   └── PaperCraftView.ts    # 侧边栏模板选择视图
    ├── templates/
    │   └── TemplateManager.ts   # 模板管理器（16 套内置模板）
    ├── drawing/
    │   └── DrawingCanvas.ts     # SVG 绘图图层
    └── i18n/
        └── i18n.ts              # 国际化（中文/英文/日文）

---

技术架构

• BackgroundLayer 层管理系统：纹理层与线条层合并为单条 background-image 声明，避免多层叠加导致的渲染模糊
• repeating-linear-gradient：纯 CSS 渐变生成横线、竖线、方格图案，无需图片资源
• radial-gradient：点阵图案用径向渐变实现，轻盈高效
• 草稿机制：设置面板的参数调整只更新预览区，点击「应用到笔记」才写入 Obsidian 数据
• 防御性加载：ensureCompleteSettings() 确保 data.json 损坏或字段缺失时自动补全
• 深合并模板：applyTemplate() 使用展开运算符深合并，避免浅合并导致字段丢失

---

适用场景

• 文学创作：古典稿纸质感，配以楷体或宋体，沉浸式写作体验
• 学术笔记：清爽横线 + 宋体，严谨而舒适
• 手账日记：暖色调点阵模板，记录生活的温度
• 练字书法：竖线 + 仿宋字体，还原古卷意境
• 日常笔记：护眼配色 + 舒适行距，长时间阅读不疲劳
• 知识管理：极简模板，专注内容本身

---

许可证

MIT License

致谢

• Obsidian —— 强大的知识管理工具
• 所有为中文字体生态做出贡献的开源项目

---

License

MIT License

Acknowledgments

• Obsidian - The powerful knowledge management tool
• All open-source projects contributing to the Chinese font ecosystem