Zettle

0025-bible-resource-class

4 min read

ADR-0025: Bible resource class — translation + structure

Status: Accepted Date: 2026-05-25

Context

The vault had 67 unresolved wikilinks pointing at resources/Bible/* (e.g. [[resources/Bible/Romans#121|1:21]]) — atomics that cite scripture as part of DP/CSG/BR arguments, written in anticipation of an ingested Bible. CONTEXT.md carried a placeholder grammar row ([[Bible/<Book>#chapterverse|<chapter>:<verse>]], “chapters as ## 3, verses as ### 16”) but no resources/Bible/<Book>.md files existed on disk, so:

  • Quartz rendered these as broken hrefs with no popover preview text — a regression in the published reader UX.
  • Pre-commit hook flagged them as missing-target after ADR-0024’s stricter validation.
  • The placeholder grammar itself had a latent collision bug: Quartz’s github-slugger strips : from ### 3:16 (slug → 316) AND from ### 31:6 (slug → 316), so e.g. Genesis 3:16 and Genesis 31:6 would resolve to the same id. Single-book Bible files cannot reliably anchor verses through the : separator.

User’s instinct (“Claude knows the Bible, do we need this?”) didn’t dissolve the question — the wikilinks are for human readers of the vault (Obsidian popover preview, hover-to-see-verse). Claude’s recall doesn’t render in a browser.

Decision

1. Translation: NIV (New International Version)

Widely recognized; closer to the diction Hendricks (BR) actually quotes; familiar to most modern Protestant readers. Sourced from resources-raw/Bible/NIV/NIV_bible.json (user-provided combined JSON from the approved source for this vault).

Alternatives rejected:

  • KJV: pure public domain, matches era of much SMM speech and early UC literature. Rejected — archaic English clashes with the modern voice of Hendricks/BR and most contemporary atomics. KJV verses cited in CSG/DP/SMM remain inline strings (always have been); they don’t need a Bible-class file to resolve.
  • BSB (Berean Standard Bible): also acceptable; public-domain redistribution-safe. Rejected here in favor of NIV recognizability; could be swapped in later by re-running scripts/ingest_bible.py --translation BSB against a BSB source file.
  • api.bible / live fetch at page-view time: avoids bulk storage but adds runtime complexity and API-key dependency. Out of scope.

2. File structure: one file per chapter, nested in book folder

resources/Bible/<BookConcat>/<chapter>.md — e.g. resources/Bible/Genesis/3.md, resources/Bible/1Samuel/17.md. BookConcat strips whitespace from canonical book names (“1 Samuel” → “1Samuel”, “Song Of Solomon” → “SongOfSolomon”) to match the existing wikilink convention.

This breaks from the original CONTEXT.md grammar (“one file per book”). The reason: per-book files force the ### 3:16 heading shape, which collides under Quartz slugification (see Context). Per-chapter files reduce verse headings to just ### N, which slugifies to N and is unique within the file.

Cost: 1189 chapter files (66 books × ~18 chapters avg). Negligible — ~5 MB of markdown, build cost stays under 5 min.

3. Citation form

[[resources/Bible/<Book>/<chapter>#verse|<verse>]]              e.g. [[resources/Bible/John/3#16|16]]
[[resources/Bible/<Book>/<chapter>#verse-verseend|<verse>-<verseEnd>]]   range: [[resources/Bible/Romans/8#29-30|29-30]]
[[resources/Bible/<Book>/<chapter>]]                       whole chapter: [[resources/Bible/Joshua/1]]

CONTEXT.md row updated to match. Existing 67 vault wikilinks migrated via scripts/migrate_bible_wikilinks.py (one-off; kept in-tree as provenance). 3 chapter-range wikilinks (Bible/Joshua#3-4, Bible/Exodus#25-31, Bible/Exodus#7-12) have no natural anchor in the per-chapter scheme and require hand-fix.

4. Ingestion approach

scripts/ingest_bible.py — translation-agnostic. Reads either a combined JSON file (one top-level object keyed by book) or a directory of per-book JSONs, emits per-chapter markdown. Run once per translation:

python3 scripts/ingest_bible.py --source resources-raw/Bible/NIV/NIV_bible.json --translation NIV

Re-runnable; output is deterministic from source.

5. Scope

66-book Protestant canon. Deuterocanon deferred — UC theology cites the Protestant Bible; deuterocanonical books can be added later as a sibling folder if needed.

Consequences

  • (+) 64 of 67 previously-broken Bible wikilinks now resolve to real chapter files (3 chapter-range cases need hand-fix).
  • (+) Per-chapter file structure has a clean anchor model with no collision risk.
  • (+) ingest_bible.py is translation-agnostic — swap translations by re-running with a different --translation and source.
  • (+) Existing convention preserved for book-folder naming (1Samuel, 1Corinthians, etc.) — old wikilinks like [[resources/Bible/1John#32|3:2]] migrate cleanly.
  • (−) CONTEXT.md Bible grammar row reshaped — file granularity changed from “per book” to “per chapter”. One-line table edit.
  • (−) Repository gains 1189 small files (~5 MB total). Quartz build cost stays under 5 minutes.

Migration provenance

Ingested and migrated on 2026-05-25 via scripts/ingest_bible.py and scripts/migrate_bible_wikilinks.py. The 3 chapter-range wikilinks listed above are out-of-scope for the migration script and are flagged for manual rewrite in a follow-on commit.

Graph View