YAML Tutorial Guide

What Is YAML?

YAML is a plain-text format for storing structured information. It is often used for configuration files, metadata, settings, and content frontmatter.

YAML is designed to be easier for humans to read than formats like JSON or XML. It uses indentation, colons, dashes, and simple key-value pairs.

A helpful way to think about YAML:

YAML is like a clean notebook page for structured facts.

Instead of writing everything as a paragraph, you organize information into labels and values.

Why YAML Matters

YAML shows up in many modern web development tools and documentation systems. You may see it in:

For Astro and Starlight, YAML is especially useful because it can store page information at the top of Markdown files.

The Basic Shape of YAML

The most basic YAML structure is a key and a value.

title: "YAML Tutorial Guide"
level: "Beginner"
topic: "Astro and Starlight frontmatter"

The word before the colon is the key. The information after the colon is the value.

key: value

You can read this like a label on a form.

title: "YAML Tutorial Guide"

This means:

The title is YAML Tutorial Guide.

YAML Frontmatter

In Astro, Starlight, Markdown, and MDX files, YAML often appears inside a frontmatter block.

Frontmatter is placed at the very top of the file between three dashes:

---
title: "Introduction to Vercel"
description: "A beginner guide to deploying a website with Vercel"
---

# Introduction to Vercel

This is the visible page content.

The YAML section gives the page metadata. The Markdown section gives the page content.

Frontmatter = information about the page
Markdown = the content of the page

YAML in an Astro or Starlight Lesson

A lesson page might begin like this:

---
title: "Using Astro and Starlight"
description: "Learn how to build a documentation site with Astro and Starlight."
sidebar:
  order: 3
level: "Beginner"
tags:
  - Astro
  - Starlight
  - Markdown
  - Web Development
---

# Using Astro and Starlight

This lesson explains how to create and organize a documentation site.

Notice that the page has a title, description, sidebar order, difficulty level, and tags.

This information can be used by the site to organize pages, create navigation, display labels, or build indexes.

Strings

A string is text.

name: "Aurelian Rassendyll"
role: "Protagonist"
region: "Europe"

Quotes are not always required, but they are often helpful because they make the value clear.

name: Aurelian Rassendyll

This can work, but quoted strings are safer when your text contains punctuation, special characters, or words that could be misunderstood.

Numbers

Numbers do not usually need quotes.

strength: 12
dexterity: 15
constitution: 13
level: 5

If the value is meant to behave like a number, leave it unquoted.

If the value is more like a label, code, or identifier, quotes may be better.

year: 2175
id: "character-001"

Booleans

A boolean is a true-or-false value.

published: true
featured: false
hasMagic: true
hasSpoilers: false

These are useful for turning options on or off.

Lists

YAML lists use dashes.

tags:
  - Worldbuilding
  - Characters
  - Astro
  - Starlight

This means the key tags has multiple values.

You can read it like this:

tags include Worldbuilding, Characters, Astro, and Starlight.

Nested Information

YAML uses indentation to show that information belongs inside other information.

character:
  name: "Veritas Miraculo"
  house: "House Miraculo"
  role: "Heir Apparent"
  status: "Active"

Here, name, house, role, and status are all inside character.

Indentation matters. Use spaces, not tabs.

Objects

An object is a group of related key-value pairs.

attributes:
  strength: 10
  dexterity: 14
  constitution: 12
  intelligence: 16
  wisdom: 15
  charisma: 18

This is useful for RPG-style character sheets because the stats belong together under one category.

Lists of Objects

You can also create a list where each item has multiple fields.

relationships:
  - name: "Aurelian Valoire VI"
    type: "True ruler"
    status: "Hidden"
  - name: "Elisande Serrat"
    type: "Political connection"
    status: "Active"
  - name: "Veritas Miraculo"
    type: "Rival"
    status: "Dangerous"

Each dash begins a new relationship. The indented lines describe that relationship.

YAML for a World Bible Character Sheet

Here is a practical YAML frontmatter example for a fictional character page.

---
title: "Veritas Miraculo"
type: "character"
setting: "2175"
region: "Europe"
house: "House Miraculo"
role: "Heir Apparent / Rival"
status: "Active"

attributes:
  strength: 10
  dexterity: 14
  constitution: 12
  intelligence: 16
  wisdom: 15
  charisma: 18

skills:
  - Diplomacy
  - Strategy
  - Court Politics
  - Investigation
  - Deception

relationships:
  - name: "Aurelian Valoire VI"
    type: "Political target"
    status: "Suspicious"
  - name: "Aurelian Rassendyll"
    type: "Potential impostor"
    status: "Under investigation"

story:
  firstAppearance: "Europe storyline"
  arc: "Discovers the ruler may not be who he claims to be."
  secret: "She is more ruthless than her public image suggests."
---

# Veritas Miraculo

## Identity

## Background

## Role in the Story

## Personality

## Goals

## Secrets

## Arc

The YAML stores the structured sheet. The Markdown below it stores the readable character article.

YAML for a Location Page

---
title: "Manhattan Harbor"
type: "location"
setting: "2175"
region: "North America"
category: "Urban / Maritime / Political"
importance: "Major"

features:
  - Suborbital transit access
  - Harbor security grid
  - Diplomatic arrival corridors
  - Corporate towers

storyUses:
  - Political meetings
  - Smuggling routes
  - High-society gatherings
  - Surveillance scenes
---

# Manhattan Harbor

## Overview

## History

## Current Role

## Narrative Uses

YAML for a Lesson Page

---
title: "JavaScript Array Reduce"
type: "lesson"
course: "JavaScript Fundamentals"
level: "Intermediate"
order: 12
estimatedTime: "45 minutes"

objectives:
  - Explain what reduce does
  - Trace the accumulator and current value
  - Build a sum function
  - Build a grouped object from an array

prerequisites:
  - Arrays
  - Callback functions
  - Loops

resources:
  - title: "MDN reduce documentation"
    type: "reference"
  - title: "Practice challenge"
    type: "exercise"
---

# JavaScript Array Reduce

## What You Are Learning

## Why It Matters

## Step-by-Step Explanation

## Practice

Indentation Rules

YAML depends on indentation. This is one of the most important rules.

Good:

attributes:
  strength: 12
  dexterity: 14
  constitution: 13

Bad:

attributes:
strength: 12
  dexterity: 14
 constitution: 13

Use consistent spaces. Two spaces is common.

Use spaces.
Do not use tabs.
Keep indentation consistent.

Common YAML Mistakes

Missing Space After a Colon

Bad:

title:"My Page"

Good:

title: "My Page"

Inconsistent Indentation

Bad:

stats:
  strength: 12
   dexterity: 14

Good:

stats:
  strength: 12
  dexterity: 14

Forgetting Quotes Around Complicated Text

Safer:

description: "A political rival: charming, strategic, and dangerous."

Using Tabs

Bad idea:

character:
	name: "Example"

Use spaces instead.

YAML Compared to JSON

YAML and JSON can store similar kinds of data. YAML is usually easier to read. JSON is stricter and more common when computers exchange data.

YAML:

title: "Character Sheet"
stats:
  strength: 12
  dexterity: 14
tags:
  - RPG
  - Worldbuilding

JSON:

{
  "title": "Character Sheet",
  "stats": {
    "strength": 12,
    "dexterity": 14
  },
  "tags": ["RPG", "Worldbuilding"]
}

Both describe the same kind of information, but YAML is often cleaner for humans to edit inside content files.

When to Use YAML

Use YAML when you want structured information that humans can edit easily.

When Not to Use YAML

YAML is not always the best choice.

Astro and Starlight Mental Model

For Astro and Starlight, think of each content page as two layers:

YAML frontmatter = the page's data card
Markdown body = the page's readable article

Example:

---
title: "The Kingdom of Example"
type: "region"
tags:
  - Geography
  - Government
  - Economy
---

# The Kingdom of Example

This is the article about the region.

Practice Exercise

Create YAML frontmatter for a fictional RPG character.

Include:

Starter:

---
title: ""
type: "character"
role: ""
level: 1

attributes:
  strength: 10
  dexterity: 10
  constitution: 10
  intelligence: 10
  wisdom: 10
  charisma: 10

skills:
  - 
  - 
  - 

equipment:
  - 
  - 
  - 

relationships:
  - name: ""
    type: ""
    status: ""
---

Practice Solution Example

---
title: "Mira Ashvale"
type: "character"
role: "Scout / Reluctant Diplomat"
level: 3
status: "Active"

attributes:
  strength: 9
  dexterity: 16
  constitution: 12
  intelligence: 13
  wisdom: 15
  charisma: 11

skills:
  - Stealth
  - Survival
  - Archery
  - Negotiation

equipment:
  - Recurve bow
  - Weather cloak
  - Field journal
  - Signal mirror

relationships:
  - name: "Captain Orin Vale"
    type: "Mentor"
    status: "Trusted"
  - name: "The Glass Court"
    type: "Political threat"
    status: "Hostile"
---

Cheat Sheet

# Key-value pair
title: "My Page"

# Number
level: 5

# Boolean
published: true

# List
tags:
  - One
  - Two
  - Three

# Nested object
attributes:
  strength: 12
  dexterity: 14

# List of objects
relationships:
  - name: "Character One"
    type: "Ally"
  - name: "Character Two"
    type: "Rival"

# Frontmatter block
---
title: "My Markdown Page"
description: "A page with YAML metadata."
---

Summary

YAML is a readable way to store structured information. In Astro and Starlight, it is commonly used as frontmatter at the top of Markdown and MDX files.

For a world bible, YAML can hold the character sheet, location metadata, faction details, story role, tags, and page organization. Markdown can hold the longer explanation, backstory, and narrative notes.

The most important YAML habits are: