Linter插件详细指南

Obsidian Linter 插件 - Markdown 和 YAML 自动格式化完全指南

#resource / obsidian #type / howto #status / evergreen

[!info] related notes

Linter 插件详细指南

核心功能：Markdown 和 YAML 格式化、自动时间戳更新、代码格式规范化
难度级别：⭐⭐⭐
推荐指数：⭐⭐⭐⭐⭐
必装程度：必装（保证格式一致性）

功能概览

核心特性

功能说明场景
标题格式化自动调整标题前后空行统一文档结构
列表格式化规范列表标记与缩进保持层级清晰
YAML 格式化自动排序 YAML 键值元数据一致
时间戳更新自动更新 updated 字段追踪修改历史
代码块格式格式化代码块语言标记代码高亮统一
链接格式规范 Wiki Link 写法链接一致性
逗号转换中英文逗号转换国际化规范

Linter vs 手动编辑

项目手动编辑Linter
时间成本高自动
一致性易出错100% 一致
更新 updated 字段需手工自动
学习成本无低

安装与配置

安装插件

  1. Settings → Community plugins → Browse
  2. 搜索 “Linter”
  3. 安装并启用

推荐配置（开箱即用）

Settings → Linter

# 核心规则启用
Heading Blank Lines:
  enabled: true
  bottom: 1        # 标题后 1 空行

YAML Key Sort:
  enabled: true    # 自动排序 YAML 键

Trailing Spaces:
  enabled: true    # 删除行末空格

Two Spaces Between Lines:
  enabled: false   # 关闭（否则会删除多个空行）

No Trailing Punctuation in Heading:
  enabled: true    # 标题末尾无标点

List Consistent Markers:
  enabled: true    # 列表标记统一

Paste as Plain Text:
  enabled: true    # 粘贴为纯文本

# 时间戳更新（关键功能）
YAML Timestamp:
  enabled: true
  date_format: "YYYY-MM-DD HH:mm:ss"
  key: "updated"   # 自动更新 updated 字段
  insert_after: "created"

格式化时机

Lint on Save:
  enabled: true    # 保存时自动格式化

Lint on Change:
  enabled: true    # 输入时实时格式化（可能影响性能）

常见规则详解

1. 标题格式化（Heading Blank Lines）

规则：标题前后空行数

# ❌ 错误示例

内容
## 子标题
继续内容

# ✅ 正确示例

内容

## 子标题

继续内容

配置

Heading Blank Lines:
  top: 1      # 标题前 1 空行（H1 除外）
  bottom: 1   # 标题后 1 空行

2. YAML 自动排序（YAML Key Sort）

作用：让 YAML 字段按字母顺序排列，便于查找

# ❌ 乱序
---
title: "笔记"
tags:
  - tech
created: 2025-12-08
updated: 2025-12-08
---

# ✅ 自动排序
---
created: 2025-12-08
tags:
  - tech
title: "笔记"
updated: 2025-12-08
---

配置

YAML Key Sort:
  enabled: true
  sort_yaml_keys: true

3. 时间戳自动更新（最有用！）

作用：保存时自动更新 updated 字段

---
title: "我的笔记"
created: 2025-12-01 10:00:00
updated: 2025-12-08 14:30:45  # ✨ 自动更新为当前时间
---

配置

YAML Timestamp:
  enabled: true
  format: "YYYY-MM-DD HH:mm:ss"  # 时间格式
  key: "updated"                   # 字段名
  insert_after: "created"          # 在 created 后插入

4. 列表格式化（List Consistent Markers）

# ❌ 混乱标记
- 项目 1
* 项目 2
+ 项目 3

# ✅ 统一为 -
- 项目 1
- 项目 2
- 项目 3

5. 行末空格清理（Trailing Spaces）

# ❌ 行末有空格（看不见）
内容…[空格][空格]

# ✅ 删除空格
内容

6. 代码块语言标记

# ❌ 没有语言标记

function test() {}


# ✅ 有语言标记
```javascript
function test() {}

---

## 工作流示例

### 场景 1：维护一致的 YAML 元数据

**启用规则**

```yaml
YAML Key Sort: ✅
YAML Timestamp: ✅

效果

每次保存笔记：
1. YAML 字段自动按字母排序
2. updated 字段自动更新为当前时间
3. 确保所有笔记格式一致

配置示例

# 排序规则（自定义键顺序）
Yaml Key Sort Order:
  - title
  - created
  - updated
  - tags
  - status
  - description

场景 2：统一 Markdown 格式

启用规则

Heading Blank Lines: ✅
List Consistent Markers: ✅
Trailing Spaces: ✅
No Trailing Punctuation in Heading: ✅

效果

每次保存笔记：
1. 标题前后自动加空行
2. 列表标记统一为 -
3. 删除行末空格
4. 标题末尾无标点

场景 3：代码块格式化

启用规则

Code Block Language:
  enabled: true
  
Paste as Plain Text:
  enabled: true

常见问题

Q1：如何禁用某些规则？

方法 1：在 Settings 中关闭

Settings → Linter → 找到规则 → disable

方法 2：使用前置命令禁用（单个笔记）

---
lint_ignore:
  - Heading Blank Lines
  - YAML Key Sort
---

Q2：为什么时间戳没有更新？

原因 1：未启用规则

Settings → Linter → YAML Timestamp → enabled: true

原因 2：字段名不匹配

# ✅ 正确：使用插件指定的字段名
---
created: 2025-12-01 10:00:00
updated: 2025-12-08 14:30:45
---

# ❌ 错误：字段名不对
---
created_time: 2025-12-01
modified_time: 2025-12-08
---

原因 3：格式不匹配

检查时间格式是否与配置一致

Q3：Linter 删除了我想保留的空行？

解决方案

Settings → Linter → Two Spaces Between Lines → disabled
或者在笔记中添加：
---
lint_ignore:
  - Two Spaces Between Lines
---

Q4：如何保留特定笔记的原始格式？

---
lint_ignore:
  - Heading Blank Lines
  - List Consistent Markers
  - YAML Key Sort
---

Q5：代码块的语言标记被改错了怎么办？

Settings → Linter → Code Block Language
→ 配置要忽略的语言
或手动指定：
```javascript [keep]
// 加上 [keep] 防止被修改

---

## 完整规则列表

### Markdown 规则

| 规则 | 功能 | 推荐 |
|-----|------|------|
| Heading Blank Lines | 标题空行 | ✅ |
| List Consistent Markers | 列表标记统一 | ✅ |
| No Trailing Punctuation in Heading | 标题末无标点 | ✅ |
| Trailing Spaces | 删除行末空格 | ✅ |
| Two Spaces Between Lines | 段落间隔 | ⚠️ |

### YAML 规则

| 规则 | 功能 | 推荐 |
|-----|------|------|
| YAML Key Sort | YAML 排序 | ✅ |
| YAML Timestamp | 时间戳更新 | ✅ |
| YAML Title Alias | 标题别名 | ⚠️ |

### 代码规则

| 规则 | 功能 | 推荐 |
|-----|------|------|
| Code Block Language | 代码块语言 | ✅ |
| Paste as Plain Text | 纯文本粘贴 | ✅ |

---

## 最佳实践

1. **启用 Lint on Save**
   - 自动保存时自动格式化
   - 无需手动操作

2. **配置时间戳更新**
   - 追踪笔记修改历史
   - 便于知识库统计

3. **统一 YAML 排序**
   - 提高可读性
   - 便于版本控制

4. **定期检查日志**

Ctrl+Shift+I → Console 查看 Linter 的运行日志


5. **根据需求调整规则**
- 并非所有规则都适合所有人
- 测试找到最合适的配置

---

## 与其他插件的配合

**Templater + Linter**
- Templater 生成初始结构
- Linter 自动格式化和更新时间戳

**Periodic Notes + Linter**
- 生成日记时 Linter 自动规范格式

**Dataview + Linter**
- Linter 保持 YAML 格式一致
- Dataview 精准查询元数据

---

## 📚 相关文档

- [[templater-plugin-guide]] - 配合 Templater 创建规范化笔记
- [[periodic-notes-plugin-guide|Periodic Notes 插件详细指南]] - 自动生成周期笔记
- [[obsidian-writing-workflow]] - 完整的写作系统

---
创建于 2025/12/8 更新于 2026/5/27