obsidian-markdown-structure

Original：🇺🇸 English

Translated

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

1installs

Sourcejykim/claude-obsidian-skills

Added on2026-02-10

NPX Install

npx skill4agent add jykim/claude-obsidian-skills obsidian-markdown-structure

SKILL.md Content

View Translation Comparison →

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

obsidian-markdown-structure

NPX Install

Tags

SKILL.md Content

Markdown Structure Validation

When to Use This Skill

Core Structure Rules

1. Frontmatter Positioning

2. Heading Hierarchy

3. Content Organization

4. Quote Block Formatting

Structure Validation Workflow

Step 1: Check Frontmatter

Step 2: Check Heading Hierarchy

Step 3: Check Content Organization

Step 4: Content-Type Specific

Quality Checklist