# Obsidian Markdown Structure

> Validate and enforce markdown document structure including frontmatter positioning, heading hierarchy, and content organization. Use when creating or validating markdown files.

- Skill: `majiayu000/obsidian-markdown-structure` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/obsidian-markdown-structure`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/obsidian-markdown-structure/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Marketing & Growth
- License: MIT
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/obsidian-markdown-structure

---


# Markdown Structure Validation

Enforce consistent markdown structure across all vault content.

## When to Use This Skill

Activate when you need to:
- Create new markdown documents
- Validate document structure
- Fix structural issues
- Ensure consistent formatting

## Core Structure Rules

### 1. Frontmatter Positioning

**Single YAML block at top, blank line after**:
```markdown
✅ CORRECT:
---
title: Document Title
created: 2025-10-31
tags:
  - tag1
---

## First Section Header
Content starts here...

❌ INCORRECT:
---
title: Document Title
---
## First Section (no blank line)

❌ INCORRECT:
## 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.

### 2. Heading Hierarchy

**Start with H2, no H1 duplication**:
```markdown
✅ CORRECT:
---
title: Document Title
---

## Introduction
Content...

### Subsection
Content...

❌ INCORRECT:
# Document Title (duplicates frontmatter title)

## Section
```

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

### 3. Content Organization

**Summary-first structure**:
```markdown
✅ CORRECT:
---
frontmatter
---

## Summary
Overview of key points...

## Main Content
Detailed content...

## Related Topics
Links and connections...

❌ INCORRECT:
---
frontmatter
---

This is content without a heading.

## First Section
```

### 4. Quote Block Formatting

**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
```

## Structure Validation Workflow

### Step 1: Check Frontmatter
```markdown
Verify:
- [ ] Single YAML block at top
- [ ] Blank line after closing ---
- [ ] All required properties present
- [ ] Consistent property names
```

### Step 2: Check Heading Hierarchy
```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
```markdown
Verify:
- [ ] No content before first heading
- [ ] Summary/overview section first
- [ ] Sections follow logical order
- [ ] Proper quote formatting
```

### Step 4: Content-Type Specific
```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