Skip to content

Contributing to the Bible

How to add and format entries so the world stays consistent. Read this before your first edit.

Folder layout

docs/
├── index.md            # Home (hero banner)
├── world/              # Setting & rules
├── history/            # Timeline (single source of dated truth)
├── factions/           # One file per faction + index.md
├── characters/         # One file per character + index.md
├── regions/            # One file per region + index.md
├── units/              # One file per unit + index.md
├── codex/              # Glossary & quick reference
├── assets/             # Images, portraits, maps (create as needed)
└── stylesheets/        # extra.css (banner + hero styles)

To add a page: create the .md file, then register it under nav: in mkdocs.yml. Unlisted pages still build but won't appear in the navigation.

Formatting cheat-sheet

Banners (admonitions)

!!! note "Optional title"
    Body text, indented four spaces.

??? lore "Collapsible spoiler"
    Hidden until clicked.

Types available: note tip warning danger quote example — plus the custom lore type (purple book icon) defined in stylesheets/extra.css.

You can also use the GitHub-style syntax, which renders identically:

> [!warning]
> Short inline banner.

Quotes

Standard blockquotes work everywhere. For a centered in-world epigraph, use the epigraph class:

<blockquote class="epigraph" markdown>
"Hope is a supply like any other. I ration it."
<cite>— Administrator Idris Vale</cite>
</blockquote>

Tables

Plain GitHub-flavored markdown tables (used throughout — see any faction page).

Use relative paths so the site works on GitHub Pages under a subpath:

[Idris Vale](../characters/idris-vale.md)
[the Seed-Heart](../codex/glossary.md#seed-heart)

Images / banners

Put files under docs/assets/… and reference them relatively:

![Map of Nandana](../assets/regions/nandana.png){ width="480" }

For a full-width hero, copy the lore-hero block from index.md.

Consistency rules

  1. The Timeline is authoritative for dates. Match it or change it deliberately.
  2. Balance numbers live in your combat data, not the bible. Unit pages own feel and reason, not HP.
  3. Every faction and character gets a contradiction — a want that conflicts with someone, and a wound.
  4. Link generously. A name mentioned twice deserves its own page and a link.
  5. Never resolve the central mystery. Were the Progenitors benefactors or slavers? Was humanity made or carried? Keep evidence on both sides; let characters argue; never let the bible decide.
  6. Nothing exotic is human-made. Every energy weapon, blade, cloak, or teleport in the Colony's hands is salvaged Progenitor tech. This one rule keeps the arsenal coherent.

Local preview

pip install -r requirements.txt      # first time only
mkdocs serve                         # live preview at http://127.0.0.1:8000
mkdocs build                         # output to site/ (git-ignored)

Publishing is automatic: pushing to main triggers .github/workflows/deploy.yml, which builds the site and deploys it to Cloudflare Pages. See the README for repo and Cloudflare setup.