library

Per-book metadata lookup macros — language-aware title, subtitle, description accessors that fall back through (lang → en → primaryLang).

≈ 4 min read 771 words Updated 2026-11-20

On this page

macros/library.html exposes accessor macros that read a Library book’s metadata dictionary and return the right localized string for the current language. The macros encode a consistent fallback chain so callers never need to write it manually.

Source: themes/bifrost/templates/macros/library.html

Public API#

{%/* import "macros/library.html" as library */%}

{%/* set book = load_data(path="library/the-book-which-tells-the-truth/_meta.json") */%}

{{ library::get_book_title(book_data=book, lang=detected_lang) }}
{{ library::get_book_subtitle(book_data=book, lang=detected_lang) }}
{{ library::get_book_description(book_data=book, lang=detected_lang) }}
{{ library::get_book_version_title(book_data=book, lang=detected_lang) }}
{{ library::get_book_short_version_title(book_data=book, lang=detected_lang) }}
{{ library::lang_name(code=book.originalLang) }}
{{ library::render_verse(
    verse=verse,
    chapter_n=chapter.n,
    lang=detected_lang,
    original_lang=book.originalLang,
    ref_paragraph_text="",
    ref_label="",
    portrait_registry=portrait_registry
) }}

ref_label names the source on the reference line, such as “World English Bible”. library-book.html falls back to “Reference translation” when the parallel book has no versionTitles.

Fallback chain#

Every accessor walks the same chain so missing translations degrade gracefully:

  1. book_data.<field>[<lang>] — the requested language.
  2. book_data.<field>.en — English fallback.
  3. book_data.<field>[book_data.primaryLang] — the book’s primary language (only for get_book_title).
  4. Empty string — for missing translations.

Version labels#

get_book_version_title and get_book_short_version_title read the Sefaria-style versionTitles and shortVersionTitles fields from _meta.json. These are edition labels, not work titles: for example, Genesis is the book title and Wheel of Heaven Translation is the version title.

The library book template also reads the structured version object from _meta.json and renders a compact provenance panel when present. That panel uses lang_name for source-language and witness labels, and surfaces license, source record, base text, method, witness stack, and responsibility metadata without changing older book records.

Portrait registry#

render_verse accepts an optional portrait_registry loaded from data/personality_portraits.json. When a paragraph’s speaker matches a known alias in that registry, the macro renders a compact linked avatar in the verse gutter. The library book sidebar separately reads the book-level portraits array from _meta.json to show people, speakers, and major figures relevant to the book.

Why these are macros, not template helpers#

Library book pages reuse these accessors in multiple positions (title bar, breadcrumbs, related-books panel, OG meta tags). Centralising the fallback logic in one macro means every position renders the same string for the same book in the same language.

Edition alignment notices#

render_verse and get_paragraph_text respect optional alignment[lang] metadata. A shared English passage labels its covered reference IDs; later units link back to it. An absent English counterpart displays an edition notice with an expandable French source instead of presenting French as an English translation. The reference IDs, source text, and annotation controls remain available. See Library Book Format for the data contract.

The book template also reads book_data.audioHold[detected_lang]. While that message is set, both featured and sidebar Listen controls are withheld and the message is shown in the sidebar. This allows a corrected reading edition to ship without exposing stale audio reference timings.

Edition notices use library-book__edition-note, which stays visible without the reference-translation toggle and inherits theme-aware link colors. The reader resolves kindByLang[detected_lang] before kind, so translated paragraphs can flow across reference units without changing the source-language layout. render_verse accepts optional preserve_paragraph_breaks (default false); the book template supplies book_data.preserveParagraphBreaks[detected_lang] to retain blank-line breaks within translated reference units. Verses with notes render an always-visible bracketed commentary marker at the end of the translated line; see Study tools → Commentary marker.

Canon scripture citations#

The three Raëlian canon books cite scripture inline, for example “(Exodus, III-2)”. render_verse accepts an optional citations map, and formatted_text an optional links list, which wrap each such citation in a quiet link to the cited verse of the Wheel of Heaven translation (/library/exodus-woh/#c3p2). library-book.html loads the map from data/canon_citations/{book-slug}.json (absent for every other book, so nothing changes there).

The map is generated by scripts/build_canon_citations.py in the www repo and committed, since Cloudflare Pages runs only Zola. Re-run it whenever data/library changes, for instance after new translated chapters are published. The script parses the French original for book, chapter and first verse, aligns each translation by the position of its citations, and parses English-edition citations of the form “Matthew 13: 5-9” from their own text. A link is emitted only when the cited verse exists in a translated book, and only when the citation text occurs once in the paragraph, so the replacement is exact.

The text is escaped before the citations are replaced, so the output is as safe as the plain autoescaped branch. The link class library-book__canon-cite keeps the text colour with a faint dotted underline and shows the accent colour only on hover or focus, so the reading line stays undisturbed; its title names the verse (“Exodus 3:2 — Wheel of Heaven translation”).

Edit this page on GitHub