Astro Starlight World Factbook World Bible Tutorial

What You Are Building

In this tutorial, you will create a documentation-style world bible using Astro and Starlight. The structure will be inspired by the CIA World Factbook: each fictional country, region, polity, territory, city-state, colony, or realm gets a consistent reference profile.

The final project will work like a lightweight encyclopedia:

world-bible/
  src/
    content/
      docs/
        index.mdx
        getting-started.mdx
        regions/
        countries/
        organizations/
        timelines/
        references/
  astro.config.mjs
  package.json

Each entry can include categories such as background, geography, people, society, government, economy, energy, communications, transportation, military, security, environment, and transnational issues.

Why Use Astro and Starlight?

Astro is designed for content-driven websites. That makes it a natural fit for a world bible because most pages are structured information, not complex app screens.

Starlight is Astro's official documentation framework. It gives you a ready-made documentation site with navigation, sidebar structure, Markdown/MDX pages, search, dark mode, and page organization.

Instead of manually copying complete HTML files for every country or region, you write world entries in Markdown or MDX and let Starlight handle the site shell.

The CIA World Factbook as a Model

The CIA World Factbook was a country reference resource that organized basic information about world entities. Its major categories are a useful model for fictional worldbuilding because they force you to think beyond plot and character.

For a world bible, the Factbook-style approach encourages questions like:

• Where is this nation or region located?
• What is its terrain, climate, and resource base?
• Who lives there?
• How is it governed?
• What does its economy depend on?
• How do people communicate and travel?
• What military or security systems exist?
• What disputes, borders, crises, or external pressures shape it?

This is not about copying real-world data. It is about borrowing the organizational logic: a repeatable reference profile for each place.

World Bible Categories Based on the Factbook

Use these categories as your starting template:

Install Astro

Create a new Astro project:

npm create astro@latest world-bible

When prompted, choose a minimal or empty starter. Then move into the project folder:

cd world-bible
npm install

Start the development server:

npm run dev

Your local site will usually open at:

http://localhost:4321

Add Starlight

Add the Starlight integration:

npx astro add starlight

This updates your Astro configuration and gives the project documentation-site behavior.

After Starlight is installed, your important content folder is usually:

src/content/docs/

That is where your Markdown and MDX world bible pages will live.

Basic Starlight Configuration

Open astro.config.mjs. A basic Starlight setup may look like this:

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'World Bible',
      description: 'A fictional world reference archive',
      sidebar: [
        {
          label: 'Start Here',
          items: [
            { label: 'Overview', slug: 'index' },
            { label: 'How to Use This Bible', slug: 'getting-started' }
          ]
        },
        {
          label: 'Countries and Regions',
          autogenerate: { directory: 'countries' }
        },
        {
          label: 'Organizations',
          autogenerate: { directory: 'organizations' }
        },
        {
          label: 'Timelines',
          autogenerate: { directory: 'timelines' }
        },
        {
          label: 'Reference',
          autogenerate: { directory: 'references' }
        }
      ]
    })
  ]
});

The sidebar controls how users navigate the documentation site. The autogenerate option can automatically create sidebar entries from folders.

Create the Main World Bible Index

Create this file:

src/content/docs/index.mdx

Add:

---
title: World Bible Overview
description: The central reference guide for the setting.
---

# World Bible Overview

This world bible uses a Factbook-inspired structure to organize the setting.

## Major Sections

- Countries and regions
- People and society
- Governments
- Economies
- Infrastructure
- Military and security
- Transnational issues
- Story hooks

## How to Use This Site

Use this site as the reference layer for stories, campaigns, lessons, maps, and continuity.

Create a Reusable Country Template Page

Create a folder:

src/content/docs/countries/

Then create an example country file:

src/content/docs/countries/example-republic.mdx

Add the following template:

---
title: Example Republic
description: A Factbook-style country profile for the Example Republic.
---

# Example Republic

## Overview

A short summary of the country, its role in the setting, and why it matters.

## Introduction and Background

Describe the founding, historical turning points, major wars, migrations, myths, disasters, revolutions, or dynastic changes.

## Geography

### Location

Where is this country located relative to other important places?

### Terrain

Mountains, deserts, coasts, forests, rivers, islands, underground regions, orbital habitats, or magical zones.

### Climate

Weather patterns, seasons, climate problems, magical weather, artificial climate control, or environmental hazards.

### Natural Resources

Food, water, minerals, energy sources, rare materials, sacred sites, magical substances, or strategic resources.

## People and Society

### Population

How many people live here? How are they distributed?

### Languages

Official languages, trade languages, minority languages, ritual languages, machine languages, or magical speech.

### Culture

Values, customs, social expectations, education, festivals, taboos, family structures, and daily life.

### Social Classes

Elites, workers, citizens, noncitizens, castes, guilds, clans, houses, uplifted beings, synthetics, or outsiders.

## Government

### Government Type

Republic, monarchy, corporate state, city-state, federation, theocracy, council, empire, tribal confederation, artificial intelligence administration, or hybrid system.

### Capital

Name the capital and explain why it matters.

### Administrative Divisions

Provinces, states, wards, colonies, districts, orbitals, territories, noble domains, or autonomous zones.

### Legal System

What is legal authority based on: constitution, religion, custom, royal decree, corporate contract, magical pact, or machine law?

## Economy

### Overview

What does this place produce, import, and export?

### Major Industries

Agriculture, mining, finance, manufacturing, biotech, magical crafting, tourism, extraction, military production, or data services.

### Trade

Who are the major trading partners? What are the bottlenecks or vulnerabilities?

### Inequality and Labor

Who benefits? Who is exploited? What labor systems exist?

## Energy

### Power Sources

Solar, fusion, zero-point energy, oil, coal, wind, magical crystals, divine power, geothermal, antimatter, or biological sources.

### Energy Problems

Shortages, monopolies, sabotage, environmental damage, dependence on foreign supply, or unstable magical reactors.

## Communications

### Media and Information

News, propaganda, public archives, rumor networks, couriers, net systems, magical messages, telepathy, signal towers, or censorship.

### Communications Infrastructure

Satellites, cables, printing presses, carrier birds, relay towers, quantum networks, or local mesh systems.

## Transportation

### Internal Transportation

Roads, trains, ports, canals, walking routes, airships, grav vehicles, riding animals, teleport nodes, or maglev corridors.

### External Connections

Borders, sea lanes, airports, starports, gates, bridges, tunnels, portals, or orbital elevators.

## Military and Security

### Armed Forces

Army, navy, air force, space force, city guard, knightly order, militia, mercenary companies, drones, superhero units, or magical defenders.

### Internal Security

Police, intelligence services, secret police, civic watch, corporate security, temple guards, or automated enforcement.

### Threats

Insurgency, invasion, piracy, terrorism, monsters, rogue machines, magical corruption, organized crime, or succession conflict.

## Environment

### Environmental Issues

Pollution, desertification, flooding, climate engineering, cursed land, invasive species, resource depletion, or terraforming failure.

### Protected Areas

Parks, sacred groves, wildlife preserves, restricted zones, ancient ruins, military exclusion zones, or magical sanctuaries.

## Transnational Issues

### Border Disputes

Who contests the borders and why?

### Refugees and Migration

Who is moving in, out, or through the region?

### Smuggling and Crime

What illegal trade crosses the borders?

### Diplomatic Pressure

Which larger powers influence or threaten this place?

## Story Uses

Explain how this place can be used in stories, campaigns, lessons, or plot arcs.

## Story Hooks

- A crisis exposes a weakness in the government.
- A border dispute becomes a proxy conflict.
- A rare resource attracts foreign powers.
- A reform movement threatens the ruling class.
- A disaster reveals a hidden historical truth.

## Related Pages

- Neighboring country
- Major faction
- Historical event
- Trade route
- Timeline entry

Create a Region Template

Countries are not the only useful world bible entries. You may also need regions, frontiers, seas, planets, dimensions, trade zones, or cultural spheres.

Create:

src/content/docs/regions/central-sea.mdx

Use this structure:

---
title: Central Sea Region
description: A regional profile for the Central Sea and surrounding powers.
---

# Central Sea Region

## Overview

## Geography

## Climate and Environment

## Countries and Powers

## Peoples and Cultures

## Trade and Economy

## Transportation Routes

## Military Importance

## Transnational Issues

## Historical Conflicts

## Current Flashpoints

## Story Uses

## Related Pages

Create a Reference Page for Standard Fields

A world bible becomes easier to maintain when you define what each field means.

Create:

src/content/docs/references/factbook-style-fields.mdx

Add:

---
title: Factbook-Style Fields
description: Definitions for the recurring categories used in country and region profiles.
---

# Factbook-Style Fields

## Introduction and Background

Historical summary and origin context.

## Geography

Physical location, landforms, climate, and resources.

## People and Society

Population, languages, culture, class, education, health, and social structure.

## Government

Political authority, law, administration, institutions, and legitimacy.

## Economy

Production, trade, labor, wealth, scarcity, and strategic industries.

## Energy

Power sources and energy vulnerabilities.

## Communications

Information systems, media, language networks, and censorship.

## Transportation

Movement of people, goods, armies, messages, and resources.

## Military and Security

Defense, policing, intelligence, threats, and internal stability.

## Environment

Ecological systems, hazards, conservation, and environmental damage.

## Transnational Issues

Problems crossing borders: war, refugees, smuggling, disease, piracy, diplomacy, or magical contamination.

Add a Worldbuilding Workflow

Use this workflow whenever you create a new country or region.

1. Create the page in src/content/docs/countries/ or src/content/docs/regions/.
2. Fill in the overview first.
3. Add geography and resources second.
4. Add people and society third.
5. Add government and economy fourth.
6. Add infrastructure categories: energy, communications, transportation.
7. Add security and transnational issues.
8. Finish with story uses and story hooks.

This order works because geography and resources shape culture, politics, economy, and conflict.

Suggested Folder Structure

A useful structure for a Factbook-style world bible is:

src/content/docs/
  index.mdx
  getting-started.mdx
  countries/
    example-republic.mdx
    northern-kingdom.mdx
    river-coalition.mdx
  regions/
    central-sea.mdx
    western-frontier.mdx
    old-empire-heartland.mdx
  organizations/
    trade-league.mdx
    royal-navy.mdx
    border-commission.mdx
  timelines/
    master-timeline.mdx
    age-of-expansion.mdx
  references/
    factbook-style-fields.mdx
    naming-conventions.mdx
    technology-scale.mdx
    government-types.mdx
    economic-systems.mdx

Use MDX for Richer Entries

Markdown is enough for basic pages. MDX is better when you want to include reusable components, such as warning boxes, cards, maps, timelines, or diagrams.

For example, a country page might eventually include:

<CountryStats
  population="42 million"
  capital="Harbor Crown"
  government="Constitutional monarchy"
  majorResource="Rare earth metals"
/>

That requires creating an Astro component and importing it into the MDX page. Start simple with plain headings first, then add components after the information architecture is stable.

Add Country Comparison Pages

The World Factbook is useful because it makes entries comparable. Your world bible can do the same.

Create:

src/content/docs/references/country-comparison-table.mdx

Example table:

| Country | Government | Major Resource | Major Conflict | Story Use |
|---|---|---|---|---|
| Example Republic | Federal republic | Grain and river trade | Border dispute | Political thriller |
| Northern Kingdom | Hereditary monarchy | Iron and timber | Succession crisis | Court intrigue |
| River Coalition | Merchant league | Shipping and finance | Pirate raids | Trade war |

Comparison pages help you quickly see differences and avoid making every nation feel the same.

Add Story Hooks to Every Profile

A real-world reference source is descriptive. A world bible should be descriptive and dramatic. Each entry should include story hooks.

Good story hooks usually come from pressure points:

• A scarce resource
• A contested border
• A legitimacy crisis
• A new technology
• A hidden population
• A transport bottleneck
• A military imbalance
• A cultural taboo
• An environmental hazard

Example:

## Story Hooks

- The capital depends on water from a rival state.
- A census reveals that the official population numbers are impossible.
- A new rail corridor threatens an old smuggling network.
- The military claims a border incursion, but merchants say it never happened.
- A sacred mountain also contains the country's most valuable mineral deposit.

Run and Build the Project

Start the local development server:

npm run dev

Create a production build:

npm run build

Preview the production build:

npm run preview

Astro's production output usually goes into:

dist/

Deploy to Netlify or Vercel

For most static Astro/Starlight projects, the deploy settings are straightforward.

The basic deployment flow is:

git add .
git commit -m "Create Astro Starlight world bible"
git push

Then connect the repository to Netlify, Vercel, or another static hosting provider.

Common Mistakes

Using Too Many Categories Too Soon

Start with the core categories first: overview, geography, people, government, economy, security, and story hooks. Add energy, communications, transportation, and transnational issues as the setting grows.

Creating Pages Without Comparison

If every country has a monarchy, a mountain range, elite soldiers, and rare minerals, the setting will feel repetitive. Use comparison tables to create contrast.

Writing Only Lore, Not Story Pressure

A world bible should help stories happen. Every country or region should have unresolved tensions.

Forgetting Navigation

When the site grows, navigation matters as much as content. Keep folders consistent and update the sidebar structure as the world expands.

Overbuilding Components Before the Content Exists

Do not build a complex component system first. Create several plain Markdown pages first. Once patterns become obvious, turn those patterns into components.

Practice Project

Create three fictional countries using the template:

1. A wealthy island trade republic.
2. A landlocked mountain monarchy.
3. A frontier federation with unstable borders.

For each one, fill in:

• Overview
• Geography
• People and society
• Government
• Economy
• Transportation
• Military and security
• Transnational issues
• Story hooks

Then make a comparison table showing how the three countries differ.

Suggested Next Improvements

• Add a country stats component for quick facts.
• Add region maps to each entry.
• Create a timeline section for major historical periods.
• Create a glossary of political, magical, technological, or cultural terms.
• Add relationship pages for alliances, trade routes, and conflicts.
• Add tags for countries, regions, factions, storylines, and eras.
• Create a checklist so each country profile has the same minimum fields.

Summary

Astro and Starlight are useful for a world bible because they let you build a structured documentation site from Markdown and MDX files. The CIA World Factbook is useful as a guide because it provides a repeatable way to think about countries and territories.

The key idea is simple:

Astro provides the site.
Starlight provides the documentation structure.
Markdown provides the content.
The Factbook provides the organizational model.
Your story world provides the imagination.

Source Notes

This tutorial is based on the current Astro and Starlight workflow and the general organizational categories historically used by the CIA World Factbook. The World Factbook category model is adapted here as a fictional worldbuilding structure, not as a source of fictional content.

• Astro is a content-driven web framework that can be started with npm create astro@latest.
• Starlight is Astro's documentation framework/integration for building docs sites.
• The CIA World Factbook historically organized country information into categories such as background, geography, people, government, economy, communications, transportation, military, and transnational issues, with later descriptions also including energy, environment, terrorism, and related topics.