✨ 为什么选择 LearnData？

曾经，我用 Notion、Obsidian、飞书等工具管理笔记，结果资料分散、难以分享。

笔记里的知识并不属于你，只有经过消化、应用，才会成为我们的财富。

LearnData 基于 VuePress + vuepress-theme-hope 构建，将笔记与文章聚合成可分享的知识库。

笔记 + 文章 = 知识库

笔记/博客自动化发布

🎯 核心功能

| 功能 | 说明 | | ---------------- | ----------------------------------------------- | | 📝 VuePress 驱动 | 基于 Vue 的静态站点生成器，Markdown 编写 | | 🎨 极简东方主题 | 朱砂 + 宣纸 / 暖墨黑配色，shiki vitesse 代码高亮（基于 vuepress-theme-hope）| | 📂 专题化结构 | 长文拆分为系列手册，方便查阅和学习 | | 📖 读书笔记 | docsify 独立托管，与主站分离，独立搜索 | | 🔍 全文搜索 | 默认本地搜索（slimsearch），可选 Algolia DocSearch | | 🔎 SEO / GEO | frontmatter SEO 审计脚本 + FAQ 结构化数据（FAQPage JSON-LD）| | 💬 评论系统 | 主站 Giscus，读书笔记 Waline，含阅读统计 | | 🤖 看板娘 | Live2D Widget 增加趣味性 | | 🚀 自动部署 | GitHub Actions 一键部署到 GitHub Pages / Vercel |

🚀 快速开始（TL;DR）

1. 点击 Use this template 创建你的仓库
2. 启用 GitHub Actions 的读写权限 (Settings > Actions > General)
3. 重新运行 workflow 触发部署
4. 在 Settings > Pages 中设置 gh-pages 分支为源

🍥 详细搭建步骤

按以下六步完成 LearnData 的初次搭建。整个流程不需要本地环境，全部在 GitHub 网页上完成。

1. 用模板创建你的仓库

访问 LearnData 项目页面，点击页面右上角的「Use this template」按钮，在弹出的页面中选择「Create a new repository」以创建一个基于此模板的新仓库。

2. 开放 Workflow 写权限

进入你的项目仓库，点击「Settings」>「Actions」>「General」，找到页面底部的 Workflow permissions 设置。选中 Read and write permissions 选项，点击保存。这一步确保 GitHub Page 在部署时能正确访问和修改你的仓库内容，避免因权限不足导致部署失败（报错 failed with exit code 128）。

3. 触发首次部署

进入菜单栏顶部的「Actions」页签，选择最新的 workflow。在页面右上方点击「Re-run jobs」>「Re-run all jobs」，触发 GitHub 重新生成并部署网页。如果设置无误，GitHub 会自动创建一个名为 gh-pages 的分支，并在其中部署你的页面。

4. 修改仓库名为用户主页

返回「Settings」页面，修改 Repository name 为 你的用户名.github.io。例如，如果你的仓库链接是 https://github.com/xxx/LearnData，那么 xxx 就是你的 GitHub 用户名。若该名称已被其他项目使用，系统会显示红色错误提示。

此时，你可以选择任意其他名称，例如 LearnData，部署页面路径将变为 你的用户名.github.io/LearnData。如果页面样式显示不正常，可能需要设置子域名，参考 常见问题 - 网页显示异常。

5. 设置 Pages 构建分支

在「Settings」>「Pages」>「Build and deployment」>「Branch」中，将 gh-pages 分支设置为 GitHub Pages 的源。大部分情况下，网站运行目录保持默认的 /(root) 即可。完成设置后，点击「Save」保存。

如果在此步骤中未找到 gh-pages 分支，请回到第三步重新触发一次 workflow。

6. 访问站点

设置完成后，稍等几分钟再刷新页面，你将看到一个新的访问链接提示：https://你的用户名.github.io/。此时你的个人知识库已经成功搭建。

本地运行

如需在本地预览或修改：

1. 安装 Node 与 pnpm 12（参考 VPS 环境部署）。仓库根的 pnpm-workspace.yaml 已用 allowBuilds 批准 esbuild / @parcel/watcher 的构建脚本，pnpm 12 必需（否则 pnpm i 会报 ERR_PNPM_IGNORED_BUILDS）；package.json 的 packageManager 字段也已钉住同一版本
2. 在项目目录下运行 pnpm i 安装依赖
3. 运行 pnpm docs:dev，访问 http://localhost:8080/

🔣 配置 LearnData

文档结构

文章和页面的配置可参考主目录下的 samplepage.md。其中 order 参数表示侧边栏的顺序，数字越小越靠前，支持非整数和负数。

我个人的偏好是：非干货短文 order 设在 -0.01 到 -0.99；干货长文设在 -1 到负无穷。每次新增文章在上一篇基础上递减 order 值。这种设置使我能随时记录低于 1000 字的短文，不影响干货文章的置顶排序。

src 目录结构：

src
|── .vuepress               # 网站配置
│   ├── config.ts           # 网站环境依赖和网站属性
│   ├── sidebar.ts          # 侧边栏
│   ├── navbar.ts           # 导航栏
│   ├── theme.ts            # 主题和插件
│   └── templateBuild.html  # 网页模板，网站关键词和统计
|── _posts                  # 博客文章目录
├── _temp                   # 草稿箱
├── reading                 # 读书笔记
├── encrypt                 # 加密目录（可指定其他目录）
├── anyname                 # 自定义笔记
├── blog.md                 # 博客页面
└── intro.md                # 博主个人介绍

src/.vuepress 路径下是网站的配置文件，已添加详细注释。可参考 vuepress-theme-hope 配置案例 调整。在 src/.vuepress/sidebar.ts 中修改文件夹路径，后台会自动抓取路径下的 md 文件生成侧边栏。src/.vuepress/theme.ts 包含评论插件的相关配置。

注意事项：

• LearnData 默认采用本地全文搜索（@vuepress/plugin-slimsearch）。如需改用 Algolia DocSearch，在 src/.vuepress/theme.ts 的 plugins 中取消 docsearch 区块的注释并填入配置（与本地搜索二选一）
• src/_temp 文件夹默认不同步到 GitHub，可手动在本地建立 _temp 文件夹存放草稿
• 自 VuePress 2 的 beta.54 版本起，文件夹名前缀 _ 在生成链接时会被省略（如文章路径 /_posts/ 编译为 /posts/）

看板娘

LearnData 集成了看板娘 Live2D Widget，支持随机对话、切换人物服饰和打飞机游戏。如不需要，可删除 src/.vuepress/public/live2d-widget 文件夹。

如果网站部署在子页面（例如 https://xxx.github.io/yyy），需要将子页面路径 yyy 加入到以下两个文件：

• 将 src/.vuepress/public/live2d-widget/autoload.js 第三行的 const live2d_path = "/live2d-widget/" 修改为 const live2d_path = "/yyy/live2d-widget/"
• 将 src/.vuepress/templateBuild.html 中看板娘区块的 Chat with me