Extension Features

The ChapterWise Codex extension provides a comprehensive set of tools for working with Codex files. This guide covers every feature in detail.

Syntax Highlighting

The extension provides full syntax highlighting for Codex files:

• File types: .codex.yaml and .codex.json
• Codex-aware: Recognizes Codex-specific fields like metadata, children, attributes, body
• Include directives: Special highlighting for include: statements

When you open a Codex file, the editor automatically applies appropriate colors to help you quickly identify structure, values, and any syntax issues.

Tree View Navigation

The Codex Structure panel appears in the Explorer sidebar when you have a Codex file open.

What It Shows

• Hierarchical view of all nodes in your Codex document
• Node types displayed with icons (character, location, event, etc.)
• Node names for quick identification
• Include directives shown with file paths
• Nested children properly indented

How to Use

1. Open a Codex file
2. Look for "Codex Structure" in the Explorer sidebar
3. Click any node to jump to its location in the file
4. Expand/collapse nodes to navigate complex hierarchies

Tree View Updates

The tree automatically refreshes when you: - Save the file - Run any Codex command - Switch between Codex files

Schema Validation

Real-time validation checks your Codex files against the format specification.

What It Validates

• Required fields: id, type, name for nodes
• Metadata structure: formatVersion, createdAt, etc.
• Attribute format: key, value, dataType fields
• Include paths: Verifies referenced files exist
• YAML/JSON syntax: Basic parsing errors

Viewing Errors

Errors appear in multiple places:

1. Inline squiggles: Red/yellow underlines in the editor
2. Problems panel: Full list with line numbers (Cmd+Shift+M)
3. Hover tooltips: Hover over squiggles for details

Error Types

Severity	Description
Error (red)	Must fix — invalid syntax or missing required fields
Warning (yellow)	Should fix — best practices or deprecated patterns
Info (blue)	Suggestions for improvement

Explode Codex

Command: ChapterWise Codex: Explode Codex

Extracts child nodes from a Codex file into separate files, replacing them with include: directives. Perfect for modularizing large manuscripts.

When to Use

• Breaking up a monolithic codex into manageable pieces
• Enabling multiple contributors to work on different sections
• Organizing content by type (characters, locations, events)

Options

1. Filter by type — Only extract nodes of specific types (e.g., only characters)
2. Output folder — Choose where extracted files are saved
3. Preview (Dry Run) — See what will happen before committing

How It Works

Before:

children:
  - id: char-001
    type: character
    name: "Marcus"
    body: "A Roman soldier..."

After:

children:
  - include: "./characters/char-001.codex.yaml"

New file characters/char-001.codex.yaml:

id: char-001
type: character
name: "Marcus"
body: "A Roman soldier..."

Safety Features

• Dry run mode — Preview changes without modifying files
• Confirmation prompt — Final confirmation before execution
• Existing file check — Won't overwrite existing files

Implode Codex

Command: ChapterWise Codex: Implode Codex (Merge Included Files)

The reverse of Explode — merges included files back into the parent document.

When to Use

• Consolidating modular content for export
• Preparing a single-file version for sharing
• Cleaning up temporary splits

Options

1. Create backup — Save a .backup copy before modifying
2. Process recursively — Follow includes within included files
3. Delete source files — Remove original files after merging
4. Preview (Dry Run) — See what will happen first

How It Works

Before:

children:
  - include: "./characters/char-001.codex.yaml"

After:

children:
  - id: char-001
    type: character
    name: "Marcus"
    body: "A Roman soldier..."

Empty Folder Cleanup

When deleting source files, the command also removes any folders that become empty.

Update Word Count

Command: ChapterWise Codex: Update Word Count

Counts words in body fields and updates the word_count attribute on each node.

What It Counts

• Text in body fields
• Recursively through all children
• Optionally through included files

Options

When the file contains include: directives, you'll be asked: - "Also update word counts in included files?"

Result

Each node with a body field gets a word_count attribute:

- id: chapter-01
  type: chapter
  name: "The Beginning"
  body: "It was a dark and stormy night..."
  attributes:
    - key: word_count
      name: "Word Count"
      value: 1247
      dataType: int

Use Cases

• Tracking manuscript length
• Monitoring chapter balance
• Setting word count goals

Generate Tags

Command: ChapterWise Codex: Generate Tags

Extracts meaningful tags from body content using NLP-based analysis.

Algorithm

The tag generator: 1. Tokenizes text into words and phrases 2. Filters out common stopwords 3. Counts frequency of meaningful terms 4. Boosts terms found in headings 5. Extracts both single words and two-word phrases (bigrams) 6. Returns the most significant tags

Options

1. Format:
2. Simple (strings) — Array of tag names

3. Detailed (with counts) — Objects with name and count

4. Max tags: How many tags to generate (1-100, default: 10)

5. Min occurrences: Minimum times a term must appear (1-50, default: 3)

6. Follow includes: Also process included files

Output Formats

Simple format:

tags:
  - Roman
  - Awakening
  - Senate
  - Memory

Detailed format:

tags:
  - name: Roman
    count: 15
  - name: Awakening
    count: 8
  - name: Senate Chamber
    count: 5

Smart Features

• Heading boost: Terms in markdown headings (#, ##) get extra weight
• Phrase detection: Captures meaningful bigrams like "Memory Flood"
• Capitalization: Preserves proper nouns and title cases phrases
• Stopword filtering: Removes common words (the, and, is, etc.)

Writer's View

Command: ChapterWise Codex: Open Writer's View

A focused, distraction-free view for writing body content.

Features

• Clean, minimal interface
• Focus on the current node's body text
• Easy navigation between sections
• Markdown preview support

How to Access

1. Open a Codex file
2. Run the command from the palette
3. Or right-click a node in the tree view

Auto-Fix

The extension can automatically fix certain issues in your Codex files.

What It Fixes

• Missing id fields (generates UUID)
• Missing type fields (infers from context)
• Formatting inconsistencies
• Common YAML syntax issues

How to Use

1. Look for the lightbulb icon (💡) on lines with fixable issues
2. Click the lightbulb or press Cmd+. / Ctrl+.
3. Select the suggested fix

Keyboard Shortcuts

Action	Mac	Windows/Linux
Command Palette	Cmd+Shift+P	Ctrl+Shift+P
Quick Fix	Cmd+.	Ctrl+.
Problems Panel	Cmd+Shift+M	Ctrl+Shift+M
Explorer (Tree View)	Cmd+Shift+E	Ctrl+Shift+E

Command Reference

Access all commands via the Command Palette (Cmd+Shift+P / Ctrl+Shift+P):

Command	Description
ChapterWise Codex: Explode Codex	Extract children to separate files
ChapterWise Codex: Implode Codex	Merge included files back
ChapterWise Codex: Update Word Count	Count words in body fields
ChapterWise Codex: Generate Tags	Extract tags from content
ChapterWise Codex: Open Writer's View	Focused writing mode

---

Need help? Check the Troubleshooting section in the installation guide.