Codex Lite Format (Markdown)

A simplified Codex format for Markdown files using YAML frontmatter

Last updated: 2025-12-04

Codex Lite Format

Codex Lite is a simplified format that brings Codex metadata to standard Markdown files using YAML frontmatter. It follows industry best practices used by GitHub, Jekyll, Hugo, and Obsidian while maintaining full compatibility with the ChapterWise ecosystem.

Version: 1.0
Status: Stable
Date: December 4, 2025

What is Codex Lite?
When to Use Codex Lite
YAML Frontmatter Basics
Supported Fields
Title Detection
Tag Formats
Attributes Support
Complete Examples
Codex Lite vs Full Codex
Best Practices
Validation

What is Codex Lite?

Codex Lite transforms any Markdown file into a ChapterWise-compatible codex entity by adding optional YAML frontmatter. Unlike the full Codex Format, Codex Lite is:

Flat structure only — No nested children arrays
Markdown-native — Works with any .md file
Fully optional — Every field is optional; bare Markdown files work too
Industry standard — Uses YAML frontmatter, the same format used by GitHub Docs, Jekyll, Hugo, and Obsidian

Key Features

Zero required fields — Any Markdown file is valid Codex Lite
Automatic title detection — First # H1 becomes the name if not specified
Flexible tags — Use comma-delimited strings or YAML arrays
Publishing control — Support for status, featured, and visibility
Optional attributes — Power users can add structured key-value metadata

When to Use Codex Lite

Use Codex Lite For

Simple documents — Articles, blog posts, notes, READMEs
Quick codex entries — Characters, locations, concepts without complex hierarchy
Markdown-first workflows — When you want files that work everywhere
Documentation — Technical docs, guides, specifications
Mixed repositories — Combine with full Codex files in the same project

Use Full Codex Format For

Hierarchical content — Books with chapters, series with episodes
Complex relationships — Characters with arcs, scenes with beats
Rich metadata — Multiple content sections, relations between entities
Structured projects — When you need the full recursive power of Codex

YAML Frontmatter Basics

YAML frontmatter is a block of metadata at the very beginning of a Markdown file, delimited by triple dashes (---):

---
type: character
name: "Elena Vance"
summary: "A brilliant physicist who discovers time travel"
tags: protagonist, scientist, book-one
status: published
---

# Elena Vance

Elena Vance was born in Cambridge, Massachusetts...

Rules

Must be at the very top — No content before the opening ---
Delimited by --- — Both opening and closing markers required
Valid YAML syntax — Key-value pairs, proper indentation
UTF-8 encoding — Same as the Markdown content

For more on YAML frontmatter conventions, see GitHub's YAML frontmatter documentation.

Supported Fields

All fields are optional. Use only what you need.

Core Identity Fields

Field	Type	Description
`type`	string	Entity type: `character`, `location`, `chapter`, `concept`, `note`, etc.
`name`	string	Entity name (if omitted, extracted from first H1)
`title`	string	Display title (alternative to name)
`summary`	string	Brief description or tagline
`id`	string	Unique identifier (UUID recommended)

Content & Organization

Field	Type	Description
`tags`	string or array	Comma-delimited string or YAML array
`author`	string or array	Author name(s)
`last_updated`	string	ISO-8601 date (`2025-12-04` or `2025-12-04T15:30:00Z`)

Publishing Control

Field	Type	Description
`status`	string	`published`, `private`, or `draft` (default: `private`)
`featured`	boolean	Highlight in Featured sections (`true` or `false`)

Media

Field	Type	Description
`image`	string	Primary image URL or path
`images`	array	Image gallery (see Media section)

Advanced

Field	Type	Description
`attributes`	array	Structured key-value metadata (see Attributes section)

Title Detection

Codex Lite automatically extracts the document title from your content:

Priority Order

name field in frontmatter (highest priority)
title field in frontmatter
First # H1 heading in the Markdown body
Filename (fallback)

Examples

Using frontmatter name:

---
name: "The Crystal Caves"
type: location
---

# Introduction to the Crystal Caves

Deep beneath the mountains...

Result: Name is "The Crystal Caves"

Using H1 detection:

---
type: location
summary: "A mystical underground realm"
---

# The Crystal Caves

Deep beneath the mountains...

Result: Name is automatically extracted as "The Crystal Caves"

Bare Markdown (no frontmatter):

# The Crystal Caves

Deep beneath the mountains...

Result: Name is "The Crystal Caves", type is inferred or defaults to document

Tag Formats

Codex Lite supports two tag formats for flexibility:

Comma-Delimited String (Recommended for simplicity)

---
tags: fantasy, magic-system, worldbuilding, book-one
---

YAML Array (For complex tags or programmatic use)

---
tags:
  - fantasy
  - magic-system
  - worldbuilding
  - book-one
---

Weighted Tags (Advanced)

For auto-generated or frequency-based tags, use objects with counts:

---
tags:
  - name: magic
    count: 15
  - name: crystal
    count: 8
  - name: underground
    count: 4
---

Weighted tags display with variable sizes in the ChapterWise UI, creating a tag cloud effect.

Attributes Support

For power users who need structured metadata beyond simple fields, Codex Lite supports the same attributes array as full Codex:

---
type: character
name: "Captain Marcus"
summary: "Veteran starship commander"

attributes:
  - key: rank
    name: "Military Rank"
    value: "Captain"

  - key: age
    name: "Age"
    value: 45
    dataType: int

  - key: skills
    name: "Core Skills"
    value:
      - navigation
      - diplomacy
      - tactical-combat
    dataType: array

  - key: homeworld
    name: "Homeworld"
    value: "New Terra"
    tags:
      - origin
      - backstory
---

# Captain Marcus

Marcus has served the fleet for over two decades...

Attribute Fields

Field	Type	Description
`key`	string	Machine-readable identifier (required)
`name`	string	Human-readable label
`value`	any	The value (string, number, boolean, array, object)
`dataType`	string	Type hint: `int`, `float`, `boolean`, `array`, `date`, `url`, `markdown`
`tags`	array	Classification tags for this attribute

Complete Examples

Minimal Example

The simplest Codex Lite file — just a type:

---
type: note
---

# Meeting Notes - December 4th

Today we discussed the new magic system...

Standard Example

A typical character entry:

---
type: character
name: "Aria Nightwhisper"
summary: "Elven ranger and guardian of the Northern Woods"
tags: protagonist, elf, ranger, book-one
status: published
featured: true
image: "/images/characters/aria-portrait.jpg"
author: "Jane Smith"
last_updated: 2025-12-04
---

# Aria Nightwhisper

## Background

Born under the silver moon in the heart of the Evergreen Forest, 
Aria learned the ways of the wild from her grandmother, the legendary
ranger Sylvanas Nightwhisper.

## Appearance

Tall and lithe with silver-streaked dark hair, Aria moves through
the forest like a shadow. Her eyes—one green, one amber—mark her
as one touched by the forest spirits.

## Abilities

- **Shadow Step**: Can merge with shadows for short-range teleportation
- **Beast Speech**: Communicates with forest creatures
- **Starlight Arrows**: Enchanted arrows that never miss at night

Full Example with Attributes

A comprehensive entry using all features:

---
type: character
id: "char-elena-vance-uuid"
name: "Dr. Elena Vance"
title: "Dr. Elena Vance, Quantum Pioneer"
summary: "Brilliant physicist who accidentally discovers time travel while researching quantum entanglement"
tags: protagonist, scientist, time-traveler, book-one, book-two
author: "Michael Chen"
status: published
featured: true
last_updated: 2025-12-04T15:30:00Z
image: "/images/characters/elena-lab.jpg"

attributes:
  - key: occupation
    name: "Occupation"
    value: "Quantum Physicist"

  - key: affiliation
    name: "Affiliation"
    value: "Chronos Research Institute"

  - key: age
    name: "Age"
    value: 34
    dataType: int

  - key: education
    name: "Education"
    value:
      - "Ph.D. Quantum Physics, MIT"
      - "B.S. Physics, Caltech"
    dataType: array

  - key: first_appearance
    name: "First Appearance"
    value: "Chapter 1: The Accident"

  - key: arc
    name: "Character Arc"
    value: "From skeptic to believer; learns that science and wonder can coexist"
    dataType: markdown
---

# Dr. Elena Vance

## The Accident

On March 15th, 2024, Dr. Elena Vance was running a routine 
quantum entanglement experiment when everything changed. A power 
surge, a flash of impossible light, and suddenly she found herself 
standing in her own laboratory—three days in the past.

## Background

Elena grew up in a family of scientists. Her mother, Dr. Sarah Vance,
was a Nobel laureate in chemistry. Her father, James, was an engineer
who designed satellites. From an early age, Elena learned to question
everything and trust only what could be measured and verified.

## The Journey

What began as a terrifying accident became the adventure of a lifetime.
As Elena learned to control her newfound ability, she discovered that
time itself was far stranger than any theory predicted...

## Key Relationships

- **Dr. Marcus Chen**: Her research partner and eventual love interest
- **Director Hayes**: Her skeptical boss who becomes an unlikely ally
- **The Watcher**: A mysterious figure who seems to know more than possible

Codex Lite vs Full Codex

Feature	Codex Lite	Full Codex
File Format	`.md` (Markdown)	`.codex.yaml` or `.codex.json`
Metadata Location	YAML frontmatter	Root-level YAML/JSON
Children/Hierarchy	Not supported	Full recursive children
Content Location	Markdown body	`body` field + `content` array
Relations	Not supported	Full relation support
Include Directives	Not supported	Supported
Required Fields	None	`metadata.formatVersion`
Best For	Simple documents, notes	Complex hierarchies, books
Tooling	Any Markdown editor	Codex-aware editors
Portability	Universal	ChapterWise ecosystem

# Good - minimal and focused
---
type: chapter
summary: "The hero enters the dark forest"
status: published
---

# Bad - unnecessary empty fields
---
type: chapter
name: ""
title: ""
summary: "The hero enters the dark forest"
tags: ""
author: ""
status: published
featured: false
image: ""
---

2. Use H1 for Title

Let the first H1 be your document title; use name only when it differs:

---
type: location
summary: "Ancient ruins in the desert"
---

# The Forgotten Temple

Buried beneath centuries of sand...

3. Choose Simple Tag Format

For most use cases, comma-delimited tags are cleaner:

# Preferred for simplicity
tags: fantasy, adventure, quest

# Use arrays only when needed (special characters, programmatic use)
tags:
  - "sci-fi: space opera"
  - "rating: mature"

4. Use Status for Publishing Control

status: draft      # Work in progress, only you can see
status: private    # Complete but not public
status: published  # Visible to everyone

5. Reserve Attributes for Structured Data

Use attributes when you need typed, structured metadata:

# Simple metadata - use regular fields
type: character
summary: "A brave knight"

# Structured metadata - use attributes
attributes:
  - key: stats
    value:
      strength: 18
      dexterity: 14
      wisdom: 12
    dataType: object

6. Organize Images Consistently

# Single image
image: "/images/characters/hero.jpg"

# Image gallery
images:
  - url: "/images/hero/portrait.jpg"
    caption: "Official portrait"
  - url: "/images/hero/action.jpg"
    caption: "In battle"

Validation

What ChapterWise Validates

When processing Codex Lite files, ChapterWise:

Parses YAML frontmatter — Reports syntax errors with line numbers
Extracts title from H1 — Falls back to filename if no H1
Normalizes tags — Handles both string and array formats
Validates status — Must be published, private, or draft
Validates dates — last_updated should be ISO-8601 format

Error Handling

Invalid frontmatter doesn't break the file — ChapterWise will:

Log a warning with details
Fall back to treating it as plain Markdown
Extract what metadata it can (title from H1, etc.)

Example Validation Errors

Invalid YAML syntax:

WARNING: Invalid YAML frontmatter in chapter-1.md (line 3)
  Cause: mapping values are not allowed here
  Suggestion: Check indentation and colon spacing

Invalid status value:

WARNING: Invalid status value "public" in chapter-1.md
  Valid values: published, private, draft
  Using default: private

Migration

From Plain Markdown

Add frontmatter to any existing Markdown file:

Before:

# My Character

A description of the character...

After:

---
type: character
summary: "A brief description"
tags: protagonist, fantasy
status: published
---

# My Character

A description of the character...

From Full Codex

Extract the key fields and body content:

Before (.codex.yaml):

metadata:
  formatVersion: "1.2"

type: character
name: "Hero"
summary: "The protagonist"
body: |
  A description of the character...

children:
  - type: arc
    name: "Hero's Journey"

After (.md):

---
type: character
name: "Hero"
summary: "The protagonist"
---

# Hero

A description of the character...

## Hero's Journey

(Note: Children become sections in Codex Lite)

Summary

Codex Lite is the perfect format when you want:

Simplicity — Just Markdown with optional metadata
Portability — Works with any Markdown tool
Flexibility — Use as many or as few fields as needed
Compatibility — Full ChapterWise ecosystem support

Start with a simple Markdown file, add frontmatter as needed, and let ChapterWise handle the rest.

Full Codex Format Specification — For hierarchical content
Git Projects Overview — Version control your codex files
Index File Format — Organize your project files