Back to Details

obsidian-markdown-structure

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Markdown Structure Validation

Markdown文档结构验证

Enforce consistent markdown structure across all vault content.
确保所有知识库内容的Markdown结构保持一致。

When to Use This Skill

何时使用此Skill

Activate when you need to:
  • Create new markdown documents
  • Validate document structure
  • Fix structural issues
  • Ensure consistent formatting
在以下场景激活此Skill：
  • 创建新的Markdown文档
  • 验证文档结构
  • 修复结构问题
  • 确保格式一致性

Core Structure Rules

核心结构规则

1. Frontmatter Positioning

1. Frontmatter位置要求

Single YAML block at top, blank line after:
markdown
✅ CORRECT:
---
title: Document Title
created: 2025-10-31
tags:
  - tag1
---
顶部仅保留单个YAML块，结尾后需空一行:
markdown
✅ CORRECT:
---
title: Document Title
created: 2025-10-31
tags:
  - tag1
---

First Section Header

First Section Header

Content starts here...

❌ INCORRECT:

title: Document Title

Content starts here...

❌ INCORRECT:

title: Document Title

First Section (no blank line)

First Section (no blank line)

❌ INCORRECT:
❌ INCORRECT:

Title

Title

frontmatter: here

(frontmatter not at top)

**Critical Rules**:
- One YAML block only
- Must be first thing in file
- Blank line after closing `---`
- No content before first heading

> **Note**: This skill validates frontmatter **POSITION** (where it goes in the document).
> For frontmatter **CONTENT** (properties, values, formatting), use `obsidian-yaml-frontmatter` skill.

frontmatter: here

(frontmatter not at top)

**关键规则**:
- 仅允许一个YAML块
- 必须位于文件最开头
- 闭合`---`后需空一行
- 第一个标题前不能有任何内容

> **Note**: 此Skill仅验证frontmatter的**POSITION**（在文档中的摆放位置）。
> 若需验证frontmatter的**CONTENT**（属性、值、格式），请使用`obsidian-yaml-frontmatter` Skill。

2. Heading Hierarchy

2. 标题层级规范

Start with H2, no H1 duplication:
markdown
✅ CORRECT:
---
title: Document Title
---
从H2开始，避免重复使用H1:
markdown
✅ CORRECT:
---
title: Document Title
---

Introduction

Introduction

Content...
Content...

Subsection

Subsection

Content...
❌ INCORRECT:
Content...
❌ INCORRECT:

Document Title (duplicates frontmatter title)

Document Title (duplicates frontmatter title)

Section

Section


**Hierarchy Rules**:
- Use H2 (`##`) for main sections
- Use H3 (`###`) for subsections
- Use H4 (`####`) sparingly
- Don't skip levels (H2 → H4)

**层级规则**:
- 主章节使用H2 (`##`)
- 子章节使用H3 (`###`)
- 尽量少用H4 (`####`)
- 不要跳过层级（如从H2直接跳到H4）

3. Content Organization

3. 内容组织要求

Summary-first structure:
markdown
✅ CORRECT:
---
frontmatter
---
先总结后细节的结构:
markdown
✅ CORRECT:
---
frontmatter
---

Summary

Summary

Overview of key points...
Overview of key points...

Main Content

Main Content

Detailed content...
Detailed content...

Related Topics

Related Topics

Links and connections...

❌ INCORRECT:

frontmatter

This is content without a heading.
Links and connections...

❌ INCORRECT:

frontmatter

This is content without a heading.

First Section

First Section

undefined
undefined

4. Quote Block Formatting

4. 引用块格式规范

Blockquotes with attribution:
markdown
✅ CORRECT:
> "Quote text here" - Speaker/Context

> "Knowledge is power, but enthusiasm pulls the switch."
> - Ivern Ball

❌ INCORRECT:
"Quote text" (not in blockquote)
> Quote without attribution
带署名的引用块:
markdown
✅ CORRECT:
> "Quote text here" - Speaker/Context

> "Knowledge is power, but enthusiasm pulls the switch."
> - Ivern Ball

❌ INCORRECT:
"Quote text" (not in blockquote)
> Quote without attribution

Structure Validation Workflow

结构验证工作流程

Step 1: Check Frontmatter

步骤1：检查Frontmatter

markdown
Verify:
- [ ] Single YAML block at top
- [ ] Blank line after closing ---
- [ ] All required properties present
- [ ] Consistent property names
markdown
Verify:
- [ ] Single YAML block at top
- [ ] Blank line after closing ---
- [ ] All required properties present
- [ ] Consistent property names

Step 2: Check Heading Hierarchy

步骤2：检查标题层级

markdown
Verify:
- [ ] No H1 after frontmatter (except special cases)
- [ ] Main sections use H2
- [ ] Subsections use H3
- [ ] No skipped levels
- [ ] Logical organization
markdown
Verify:
- [ ] No H1 after frontmatter (except special cases)
- [ ] Main sections use H2
- [ ] Subsections use H3
- [ ] No skipped levels
- [ ] Logical organization

Step 3: Check Content Organization

步骤3：检查内容组织

markdown
Verify:
- [ ] No content before first heading
- [ ] Summary/overview section first
- [ ] Sections follow logical order
- [ ] Proper quote formatting
markdown
Verify:
- [ ] No content before first heading
- [ ] Summary/overview section first
- [ ] Sections follow logical order
- [ ] Proper quote formatting

Step 4: Content-Type Specific

步骤4：针对特定内容类型的检查

markdown
Check content follows appropriate template structure:
- [ ] Journal: H1 title, standard sections
- [ ] Roundup: Opening quote(s), structured headers
- [ ] Events: Executive Summary, Key Takeaways, Next Actions
- [ ] Clippings: Summary first, then detailed sections
markdown
Check content follows appropriate template structure:
- [ ] Journal: H1 title, standard sections
- [ ] Roundup: Opening quote(s), structured headers
- [ ] Events: Executive Summary, Key Takeaways, Next Actions
- [ ] Clippings: Summary first, then detailed sections

Quality Checklist

质量检查清单

Before completing structure validation:
  • Single YAML frontmatter at top
  • Blank line after frontmatter
  • No content before first heading
  • Heading hierarchy correct (H2 → H3 → H4)
  • Quote blocks properly formatted
  • Summary/overview section present
  • Sections in logical order
  • Template structure followed for content type
完成结构验证前，请确认：
  • 文件顶部仅有一个YAML格式的frontmatter
  • frontmatter后空一行
  • 第一个标题前无任何内容
  • 标题层级正确（H2 → H3 → H4）
  • 引用块格式规范
  • 包含总结/概述章节
  • 章节顺序符合逻辑
  • 符合对应内容类型的模板结构