Splitting Notes

Overview

Split large monolithic note files into focused, single-topic files with index-based navigation. Reduces cognitive load and improves discoverability through progressive grouping.

When to Use

digraph when_refactor {
  "Note file size > 1000 lines?" [shape=diamond];
  "Topics mixing unrelated concepts?" [shape=diamond];
  "Hard to find specific information?" [shape=diamond];
  "Refactor notes" [shape=box];
  "Keep as-is" [shape=box];

  "Note file size > 1000 lines?" -> "Refactor notes" [label="yes"];
  "Note file size > 1000 lines?" -> "Topics mixing unrelated concepts?" [label="no"];
  "Topics mixing unrelated concepts?" -> "Refactor notes" [label="yes"];
  "Topics mixing unrelated concepts?" -> "Hard to find specific information?" [label="no"];
  "Hard to find specific information?" -> "Refactor notes" [label="yes"];
  "Hard to find specific information?" -> "Keep as-is" [label="no"];
}

Use when:

• •Note files exceed 1000 lines
• •Single file mixes unrelated topics
• •Navigation and search are difficult
• •Content needs better organization

Don't use when:

• •Files are already under 500 lines
• •Topics are tightly coupled
• •Splitting would harm coherence

Prerequisite

Complex multi-step refactoring - Must complete planning phase first.

If not currently in plan mode, invoke EnterPlanMode before starting.

• •In plan mode: Complete analysis and create migration plan
• •After plan mode: Execute split and verification

Core Pattern

Before - Monolithic file:

content/topic/large-file.md (1500+ lines)
├── H2 Chapter 1
├── H2 Chapter 2
├── H2 Chapter 3
└── ...10+ more sections

After - Modular structure:

content/topic/
├── topic.md (index, ~50 lines)
├── chapter-1.md (~200 lines)
├── chapter-2.md (~150 lines)
├── chapter-3.md (~180 lines)
└── ...remaining chapters

See examples.md for complete walkthroughs of:

• •Simple split (300 lines, Python)
• •Medium split (850 lines, Vue)
• •Complex split (1500 lines, React)

Quick Reference

Implementation

1. Planning Phase (Plan Mode Required)

Analyze the source:

• •Analyze target file and directory structure: use Glob/Grep to understand context
• •Read source file: identify all H2 sections
• •Calculate chapter sizes: count lines per section, plan split strategy

Create migration plan:

• •List target files with their H2 sections
• •Group related topics
• •Ensure sizes stay under 1000 lines

2. Execution Phase

Split by H2 sections:

• •Short chapters (<100 lines) → merge
• •Long chapters → separate file
• •Single H2 > 1000 lines → keep independent
• •Add sidebar_position and adjusted tags frontmatter to each split file

Create index file (same name as directory):

• •Progressive grouping (Getting Started → Core → Advanced)
• •Every link MUST have description
• •Format: - [Name](./path.md) - Description (no period)

See examples.md for complete index file templates.

3. Verification Checklist

• • Frontmatter added to split files (sidebar_position + tags)
• • Internal links updated (use Grep)
• • Image paths corrected (./figures/subdirectory/file.ext)
• • Index order matches sidebar_position
• • Build succeeds: pnpm build
• • Lint passes: pnpm lint:content
• • Line count verified: wc -l original new/*
• • Original file deleted
• • Use TodoWrite to mark all tasks complete

Common Mistakes

Real-World Impact

Before: python.md (1046 lines) - hard to navigate, slow to load After: 12 focused files + index - each topic immediately accessible

Search improvement: 3x faster (specific file vs scan entire document) Build time: 40% reduction (parallel processing of smaller files)