Index File Best Practices

Tips and recommendations for creating effective index.codex.yaml files

Last updated: 2025-10-15

Index File Best Practices

Learn how to create effective, maintainable index files for your Git codex projects. These best practices will help you organize your content logically and make it easy for collaborators (human and AI) to understand your project structure.

Core Principles

1. Start Simple

Begin with the minimum needed configuration:

✅ Good: Minimal, clear

structure:
  - path: "Characters/"
    order: 1
  - path: "World/"
    order: 2

❌ Avoid: Over-specification

structure:
  - path: "Characters/"
    title: "Characters"
    description: "This folder contains character files"
    expanded: false
    order: 1
    icon: "ph-folder"
files:
  - path: "Characters/hero.codex.yaml"
  - path: "Characters/villain.codex.yaml"
  # ... listing every single file

Why: Auto-detection handles most cases. Only specify what you need to customize.

2. Never Specify `type`

File types are automatically detected from extensions.

✅ Good: Let system auto-detect

files:
  - path: "characters.codex.yaml"
  - path: "README.md"

❌ Bad: Manual type specification

files:
  - path: "characters.codex.yaml"
    type: "codex"  # Unnecessary!
  - path: "README.md"
    type: "markdown"  # Unnecessary!

Why: Reduces errors, keeps files DRY, easier to maintain.

3. Use Logical Ordering

Give folders and files explicit order numbers:

✅ Good: Clear sequence

structure:
  - path: "01-Introduction/"
    order: 1
  - path: "02-Characters/"
    order: 2
  - path: "03-Worldbuilding/"
    order: 3
  - path: "04-Timeline/"
    order: 4

❌ Avoid: Alphabetical without intent

structure:
  - path: "Characters/"
  - path: "Timeline/"
  - path: "Worldbuilding/"
  # Random order based on filename

Why: Readers should encounter content in a specific, meaningful order.

4. Hide, Don't Delete

Use hidden: true for work-in-progress or archive content:

✅ Good: Hide temporarily

files:
  - path: "draft-concepts.codex.yaml"
    hidden: true  # Still in repo, just not displayed

structure:
  - path: "_WIP/"
    title: "Work in Progress"
    hidden: true

❌ Avoid: Excluding from repo

# .gitignore
draft-concepts.codex.yaml  # Lost if not committed!

Why: Hidden files stay version-controlled but don't clutter the view.

Organizational Patterns

Pattern 1: By Category

Best for: Story bibles, world-building projects

structure:
  - path: "Characters/"
    order: 1

  - path: "Locations/"
    order: 2

  - path: "Events/"
    order: 3

  - path: "Concepts/"
    order: 4

Pattern 2: By Hierarchy

Best for: Character relationships, organizational structures

structure:
  - path: "Characters/"

  - path: "Characters/Protagonists/"
    order: 1

  - path: "Characters/Protagonists/MainHero/"

  - path: "Characters/Protagonists/LoveInterest/"

  - path: "Characters/Antagonists/"
    order: 2

Pattern 3: By Timeline

Best for: Historical projects, series chronology

structure:
  - path: "01-Ancient-Era/"
    title: "Ancient History (0-1000)"
    order: 1

  - path: "02-Classical-Era/"
    title: "Classical Period (1000-2000)"
    order: 2

  - path: "03-Modern-Era/"
    title: "Modern Times (2000+)"
    order: 3

Pattern 4: By Book/Volume

Best for: Multi-book series

structure:
  - path: "Book-1/"
    title: "The Beginning"
    order: 1

  - path: "Book-1/Characters/"
  - path: "Book-1/Locations/"
  - path: "Book-1/Events/"

  - path: "Book-2/"
    title: "The Journey"
    order: 2

  - path: "Shared/"
    title: "Series-Wide Content"
    expanded: true

Pattern 5: Virtual Folders (Groups) - NEW! ⭐

Best for: Creating virtual organization that mirrors your folder structure

Key Principle: Groups mirror your folder structure, providing a virtual navigation layer while files stay in place.

# Use custom grouping
display:
  groupBy: "custom"

# Groups automatically generated from folder structure
groups:
  - name: "Characters"           # Matches "Characters/" folder
    description: "Character profiles"
    expanded: true
    order: 1
    files:
      - "Characters/hero.codex.yaml"
      - "Characters/villain.codex.yaml"
      - "Characters/mentor.codex.yaml"

  - name: "Locations"            # Matches "Locations/" folder
    order: 2
    files:
      - "Locations/capital-city.md"
      - "Locations/dark-tower.md"

  - name: "Events"               # Matches "Events/" folder
    order: 3
    files:
      - "Events/battle.md"
      - "Events/coronation.md"

How Groups Work:

Mirror Folders: Each group corresponds to a folder in your repository
Virtual Organization: Files stay in their folders, but display is customizable
Flexible Display: Reorder groups, add descriptions, control expansion
Auto-Generated: ChapterWise can auto-generate groups from your folder structure

When to Use Groups:

✅ You have a folder structure you want to enhance with metadata
✅ Need to control display order of folders
✅ Want to add descriptions to folder categories
✅ Prefer virtual navigation over filesystem hierarchy

Benefits:

📁 Files stay organized in folders
🎨 Customize how folders appear in navigation
📝 Add descriptions and icons to folder categories
🔄 Change display order without moving files
🚀 Auto-generate with one click

Best Practice:

The recommended approach is to let ChapterWise auto-generate groups from your folder structure. This creates a clean mapping between your filesystem organization and the virtual navigation layer, making it intuitive for both you and your collaborators.

Naming Conventions

Folder Names

✅ Good Practices:

structure:
  - path: "Characters/"           # Clear, simple
  - path: "Main-Characters/"      # Hyphen for multi-word
  - path: "01-Introduction/"      # Number prefix for order

❌ Avoid:

structure:
  - path: "chars/"                # Unclear abbreviation
  - path: "Characters_Main/"      # Underscore (use hyphen)
  - path: "Characters (Main)/"    # Special characters

File Titles

✅ Good:

files:
  - path: "hero-journey.codex.yaml"
    title: "The Hero's Journey"

  - path: "magic-system.codex.yaml"
    title: "Magic System Rules"

❌ Avoid:

files:
  - path: "hero-journey.codex.yaml"
    title: "hero-journey.codex.yaml"  # Just repeating filename

  - path: "magic-system.codex.yaml"
    title: "ms"  # Unclear abbreviation

Display Control

Expand Strategically

Only expand folders users should see first:

structure:
  - path: "Getting-Started/"
    expanded: true  # First thing users see

  - path: "Characters/"
    expanded: true  # Main content

  - path: "Characters/Main/"
    expanded: true  # Sub-category

  - path: "Characters/Supporting/"
    expanded: false  # Collapsed by default

  - path: "Archive/"
    expanded: false
    hidden: true  # Not shown by default

Rule of Thumb: Expand top 2-3 levels, collapse the rest.

Sort Intelligently

display:
  sortBy: "order"     # When order matters
  # OR
  sortBy: "name"      # When alphabetical is fine
  # OR  
  sortBy: "modified"  # When recent files matter

Choose based on your content: - Narrative content: Use order - Reference material: Use name - Active projects: Use modified

Pattern Matching

Include Patterns

Be specific about what to include:

✅ Good: Explicit types

patterns:
  include:
    - "*.codex.yaml"
    - "*.codex.json"
    - "*.md"
    - "docs/**/*.json"  # JSON only in docs/

❌ Too Broad:

patterns:
  include:
    - "**/*"  # Everything! Too much

Exclude Patterns

Exclude non-content directories:

✅ Good: Common exclusions

patterns:
  exclude:
    - "_ARCHIVE/**"
    - "_WIP/**"
    - "**/node_modules/**"
    - "**/.git/**"
    - "**/temp/**"
    - "**/*.backup"
    - "**/*.tmp"

Metadata Usage

Project Metadata

Add useful project information:

metadata:
  version: "2.1.0"
  authors:
    - "Primary Author"
    - "Contributing Author"
  tags:
    - "fantasy"
    - "epic"
    - "series"
  created: "2024-01-15"
  updated: "2025-10-15"
  license: "CC BY-NC-SA 4.0"
  website: "https://example.com"

File Descriptions

Add descriptions for important files:

files:
  - path: "magic-system.codex.yaml"
    title: "Magic System"
    description: "Complete rules for the magic system, including limitations and costs"

  - path: "timeline.md"
    description: "Historical timeline from creation to present day"

# ChapterWise auto-generated index cache
.index.codex.yaml
.index.codex.json

This keeps auto-generated caches out of version control while allowing committed indexes.

Workflow Options

Option 1: No Index (Recommended for Simple Projects)

# Do nothing! ChapterWise auto-generates and caches
# Creates: .index.codex.yaml (hidden, not committed)

Best for: - Simple projects - Personal use - Default filesystem organization works

Option 2: Committed Index (Recommended for Teams)

# Download from ChapterWise, edit, then commit
curl -o index.codex.yaml "https://chapterwise.app/projects/{id}/index/download"

# Edit the file
vim index.codex.yaml

# Commit and share with team
git add index.codex.yaml
git commit -m "Add custom project structure"
git push

Best for: - Team projects - Complex organization - Shared project standards

Option 3: Local-Only Customization

# Create local index (not committed)
cp .index.codex.yaml my-local-index.yaml

# Edit for your personal use
vim my-local-index.yaml

# Ensure it's ignored
echo "my-local-index.yaml" >> .gitignore

Best for: - Personal view preferences - Doesn't affect team - Testing organization ideas

Collaboration Guidelines

For Team Projects

Discuss Structure: Agree on folder organization
Document Decisions: Add comments explaining choices
Use Consistent Naming: Follow team conventions
Review Changes: Treat index updates like code reviews

For AI Assistants

When working with AI to create/modify index files:

Describe Your Project: "This is a fantasy novel with 3 main characters..."
Specify Priorities: "Characters should come first, then locations..."
Mention Special Cases: "Hide the _DRAFTS folder..."
Review Generated Result: Always check AI-generated indexes

Performance Optimization

For Large Projects (100+ files)

✅ Good Strategies:

# Use patterns to reduce scope
patterns:
  exclude:
    - "archive-*/**"  # Exclude old content
    - "**/*.backup"   # Exclude backups

# Don't list every file
structure:
  - path: "Characters/"  # Auto-scans this folder
  # No need to list individual files

❌ Avoid:

# Listing hundreds of files manually
files:
  - path: "file1.codex.yaml"
  - path: "file2.codex.yaml"
  # ... 98 more files
  - path: "file100.codex.yaml"

File Size Management

Keep index under 100KB
Use patterns instead of explicit file lists
Archive old content to separate directories

Common Mistakes

Mistake 1: Redundant Information

❌ Bad:

files:
  - path: "characters.codex.yaml"
    title: "characters.codex.yaml"  # Same as filename
    type: "codex"  # Auto-detected

✅ Good:

files:
  - path: "characters.codex.yaml"
    title: "Character Profiles"

Mistake 2: Forgetting Trailing Slashes

❌ Bad:

structure:
  - path: "Characters"  # Missing /

✅ Good:

structure:
  - path: "Characters/"  # Correct

Mistake 3: Over-Nesting

❌ Bad:

structure:
  - path: "World/Continents/NorthernContinent/Regions/Mountains/Peaks/..."
    # Too deep!

✅ Good:

structure:
  - path: "Geography/"
  - path: "Geography/Continents/"
  - path: "Geography/Regions/"
  # Stop at 2-3 levels

Mistake 4: No Ordering

❌ Bad:

structure:
  - path: "Epilogue/"
  - path: "Chapter-1/"
  - path: "Prologue/"
  - path: "Chapter-2/"
  # Random order!

✅ Good:

structure:
  - path: "Prologue/"
    order: 1
  - path: "Chapter-1/"
    order: 2
  - path: "Chapter-2/"
    order: 3
  - path: "Epilogue/"
    order: 99

Testing Your Index

Manual Testing

Create or update your index
Regenerate the file tree in ChapterWise
Check folder structure appears correctly
Verify files are in expected locations
Test search and filtering

codexVersion: "1.0"
name: "Short Story Collection"
mainFile: "README.md"

files:
  - path: "README.md"
    order: 1
  - path: "story-1.md"
    title: "The Beginning"
    order: 2
  - path: "story-2.md"
    title: "The Middle"
    order: 3
  - path: "story-3.md"
    title: "The End"
    order: 4

Medium Project (50-100 files)

codexVersion: "1.0"
name: "Fantasy Novel"
mainFile: "README.md"

structure:
  - path: "Characters/"
    order: 1
  - path: "Locations/"
    order: 2
  - path: "Magic/"
    order: 3

patterns:
  exclude:
    - "_DRAFTS/**"

Large Project (200+ files)

codexVersion: "1.0"
name: "Epic Series Bible"
mainFile: "README.md"

structure:
  - path: "Series-Overview/"
    expanded: true
    order: 1

  - path: "Book-1/"
    order: 10
  - path: "Book-2/"
    order: 20
  - path: "Book-3/"
    order: 30

  - path: "Shared-World/"
    expanded: true
    order: 100

patterns:
  exclude:
    - "archive-**/**"
    - "_drafts/**"
    - "**/*.backup"

display:
  sortBy: "order"
  groupBy: "folder"

Checklist

Before finalizing your index:

[ ] All required fields present (path for files/folders)
[ ] No type fields (auto-detected)
[ ] Folders have trailing slashes
[ ] Logical order values set
[ ] Appropriate folders set to expanded: true
[ ] Work-in-progress content marked hidden: true
[ ] Exclude patterns for non-content directories
[ ] Project metadata filled in
[ ] File tested and validated
[ ] Committed to repository (if shared)

Next Steps

View Examples - See real index files
Read Format Spec - Complete reference
Troubleshooting - Common issues