Obsidian 学习笔记

Appearance

贡献指南 ​

感谢你考虑为本知识库做出贡献！

贡献方式 ​

内容贡献 ​

欢迎贡献以下内容：

  • 新增章节和文章
  • 修正错误和错别字
  • 改进文档结构
  • 添加示例代码
  • 翻译内容

问题反馈 ​

发现问题时：

  1. 检查是否已有相关问题
  2. 创建详细的 Issue 描述
  3. 提供复现步骤（如适用）

功能建议 ​

欢迎提出改进建议：

  • 新功能想法
  • 用户体验优化
  • 性能改进建议

贡献流程 ​

Fork 工作流 ​

bash
# 1. Fork 本仓库到你的账户

# 2. 克隆到本地
git clone https://github.com/zhangweilong/obsidian-notes.git

# 3. 创建分支
git checkout -b feature/your-feature

# 4. 进行更改
# 编辑文件...

# 5. 提交更改
git add .
git commit -m "feat: 添加新章节"

# 6. 推送到 Fork
git push origin feature/your-feature

# 7. 创建 Pull Request

提交信息规范 ​

yaml
提交类型:
  feat: 新功能/新内容
  fix: 修复问题
  docs: 文档更新
  style: 格式调整
  refactor: 重构优化
  chore: 维护任务

示例:
  feat: 添加 AI 辅助功能章节
  fix: 修正安装步骤描述
  docs: 更新 API 参考文档

文档规范 ​

文件命名 ​

yaml
命名规则:
  - 使用小写字母
  - 使用连字符分隔
  - 使用有意义的名称

示例:
  ✓ getting-started.md
  ✓ plugin-development.md
  ✗ Getting Started.md
  ✗ 新建文档.md

Frontmatter ​

每个文档应包含 frontmatter：

markdown
---
title: 文档标题
description: 简短描述（用于 SEO 和预览）
---

标题结构 ​

markdown
# 主标题（H1）

简介段落...

## 二级标题

### 三级标题

#### 四级标题（尽量避免更深层级）

代码块 ​

指定语言以启用语法高亮：

markdown
```javascript
console.log('Hello');
```

```bash
npm install obsidian
```

表格 ​

markdown
| 列1 | 列2 | 列3 |
|-----|-----|-----|
| 内容 | 内容 | 内容 |

链接 ​

markdown
# 内部链接
[链接文本](/path/to/page)

# 外部链接
[链接文本](https://example.com)

内容指南 ​

写作风格 ​

  • 使用简洁清晰的语言
  • 避免冗长的句子
  • 使用主动语态
  • 提供具体示例

内容结构 ​

markdown
# 标题

简短介绍（1-2 段）

## 主要内容

### 子主题

## 示例

## 注意事项

## 相关链接

## 下一步

示例代码 ​

  • 确保代码可运行
  • 添加必要注释
  • 说明运行环境

审核流程 ​

PR 审核 ​

  1. 自动检查（格式、链接）
  2. 内容审核
  3. 建议修改（如需要）
  4. 合并到主分支

审核标准 ​

  • 内容准确性
  • 格式规范性
  • 链接有效性
  • 无拼写错误

本地预览 ​

bash
# 安装依赖
npm install

# 启动开发服务器
npm run docs:dev

# 构建生产版本
npm run docs:build

# 质量检查
npm run check          # frontmatter + 链接校验
npm run check:doc-count # 文档计数一致性校验
npm run typecheck     # TypeScript 类型检查
npm run lint          # ESLint 代码规范
npm run check:all     # 一键全量检查

插件教程映射规范 ​

插件市场通过 docs/public/data/plugin-tutorials.json 将插件与站内教程关联，并在插件详情弹窗展示「教程」入口。新增或调整教程时需遵循以下约定，避免详情弹窗出现断链：

教程存放位置 ​

  • 所有插件教程统一集中在 docs/advanced/plugin-tutorials/<id>.md（<id> 为插件在官方列表中的 ID，小写字母 + 连字符），文件名即插件 ID，与映射表键一一对应。
  • 一个插件的多篇教程（如基础 + 进阶）归并到同一个文件，以 ## 二级标题分节。
  • 通用速查表（如 reference/dataview-cheatsheet）不属于插件教程叙事，保留在 docs/reference/ 原位，教程入口可直接指向其 /reference/... 路径。
  • 新建教程后，将站内路径登记到映射表，URL 以 / 开头、不含 .md 后缀，例如 /advanced/plugin-tutorials/dataview。
  • 旧路径（迁移前所在目录）已在 docs/.vitepress/redirects.ts 配置重定向，无需手工维护外链兼容。

映射表格式 ​

plugin-tutorials.json 为扁平结构，键为插件 ID，值为其教程列表：

json
{
  "dataview": {
    "tutorials": [
      { "title": "Dataview 实战", "url": "/advanced/plugin-tutorials/dataview", "type": "advanced" }
    ]
  }
}

字段说明：

  • title：教程在详情弹窗中显示的标题
  • url：站内路由路径（需对应 docs/<path>.md 真实文件，否则会被校验脚本标记为断链）
  • type：难度标识，beginner / advanced / reference 三选一

校验 ​

执行同步脚本时，validateData 会检查：

  1. 映射表中的插件 ID 是否都在官方插件列表中；
  2. 每个教程 url 对应的 docs/<path>.md 文件是否存在（不存在则输出断链警告）。

提交前可运行 npm run sync:quick（或完整同步）触发校验。

新增文档流程 ​

1. 创建文档 ​

bash
# 在对应目录创建 .md 文件
# 文件名使用小写字母 + 连字符，如 dataviewjs-advanced.md
touch docs/advanced/your-new-doc.md

2. 添加 Frontmatter ​

yaml
---
title: 文档标题
description: 简短描述（用于 SEO 和预览，10-200 字符）
category: "进阶功能"     # 对应模块分类
tags: ["标签1", "标签2"]  # 2-5 个标签
---

3. 更新侧边栏 ​

编辑 docs/.vitepress/sidebar/index.ts，在对应分组中添加：

typescript
{ text: '你的文档标题', link: '/advanced/your-new-doc' },

4. 检查并提交 ​

bash
# 运行质量检查
npm run check
npm run check:doc-count

# 提交
git add .
git commit -m "feat: 新增文档标题"

文档结构模板 ​

markdown
---
title: 文档标题
description: 简短描述
category: "分类名"
tags: ["标签"]
---

# 文档标题

简介段落（1-2 段说明本文内容）

## 主要内容

### 子主题

## 示例

## 注意事项

## 相关文档

- [相关文档 1](/path/to/doc) — 简要说明

获取帮助 ​

  • 创建 Issue 提问
  • 在 PR 中 @ 维护者
  • 查看现有文档参考

行为准则 ​

  • 尊重所有贡献者
  • 接受建设性批评
  • 关注对社区有益的内容
  • 保持友好和专业

再次感谢你的贡献！ 🎉

👥 贡献者 ​

感谢所有为本项目做出贡献的开发者！

ZhangWeilong
ZhangWeilongMaintainer