Content Pack Format

Overview

A Content Pack (.htx) is a ZIP archive containing liturgical, biblical, or classical texts in a structured format. Horatio loads and indexes these packs for offline reading, full-text search, and calendar-based daily navigation.

Packs are self-contained: each pack bundles its texts, metadata, and code mappings. No external dependencies are required.

Pack Structure

A .htx file is a standard ZIP archive with this directory layout:

my-pack.htx
  manifest.json          # Required: pack metadata
  codes_map.json         # Required: code-to-file mapping
  texts/                 # Text fragments (BMD or plain)
    ps.001.bmd
    ps.002.bmd
    ...
  RPL/                   # Optional: replacement patterns
    MEM;0117.bmd
    AL0;0.bmd
    AL0;1.bmd

The texts/ directory can use subdirectories for organization (e.g., texts/psalms/, texts/readings/). File paths in codes_map.json are relative to the pack root.

manifest.json

The manifest describes the pack and its contents. All fields marked required must be present.

{
  "id": "georgian-breviary-sample",
  "version": "1.0.0",
  "name": "Georgian Breviary",
  "description": "Liturgy of the Hours in Georgian (Mkhedruli script)",
  "language": "kat",
  "script": "georgian",
  "text_direction": "ltr",
  "author": "PineSoft",
  "period": "Modern",
  "genre": "liturgical",
  "difficulty": "intermediate",
  "fragment_count": 42,
  "has_translations": ["lat"],
  "has_morphology": false,
  "has_audio": false,
  "required_fonts": ["NotoSansGeorgian"],
  "min_app_version": "1.0.0",
  "pack_size_bytes": 85200,
  "checksum_blake3": "a1b2c3d4...",
  "preservation_status": "vulnerable"
}

Field Reference

Optional CLEDR Fields

For liturgical packs following the CLEDR schema (CatholicOS Liturgical Event Data Registry):

codes_map.json

Maps short codes to text files. This file enables calendar-based lookup and navigation.

{
  "mapping": {
    "ps.001": {
      "file": "texts/ps.001.bmd",
      "title": "Psalmus 1 — Beatus vir"
    },
    "ps.002": {
      "file": "texts/ps.002.bmd",
      "title": "Psalmus 2 — Quare fremuerunt gentes"
    },
    "0117": {
      "file": "texts/sanctorale/0117.bmd",
      "title": "S. Antonii Abbatis",
      "cledr_id": "anthony_of_egypt_abbot",
      "rank": "MEMORIA",
      "type": "SANCTORALE"
    }
  }
}

Code Conventions

Entry Fields

BMD Markup

BMD (Bible MarkDown) is a lightweight markup extending Markdown for biblical and liturgical notation. Originally developed for ePrex (2015). Files use the .bmd extension.

Block Elements

Psalm Notation

The asterisk or plus sign must be preceded by a space and appear at the end of the line.

Inline Markup

Example BMD File

# Psalmus 22

{Ant.} Dominus pascit me, et nihil mihi deerit.

Dominus pascit me, et nihil mihi deerit; *
  in pascuis virentibus me collocat,

Ad aquas tranquillitatis conducit me, *
  reficit animam meam.

Deducit me per semitas iustitiae *
  propter nomen suum.

{V.} Gloria Patri et Filio et Spiritui Sancto.
{R.} Sicut erat in principio et nunc et semper.

Liturgical Structure Markers

For packs containing the Liturgy of the Hours, responsories, or intercessions, BMD provides additional structural markers. These are backward compatible — packs using only basic BMD markup continue to work unchanged.

Antiphon Boundaries

Antiphons bracket psalms and canticles. Use {Ant|} / {|Ant} to mark the antiphon text block:

{Ant|}
Il Signore è vicino.
{|Ant}

Dominus pascit me, et nihil mihi deerit; *
  in pascuis virentibus me collocat,

{Gloria}

{Ant|}
Il Signore è vicino.
{|Ant}

Responsory Structure

Responsories use {Rsp|} / {|Rsp} for block boundaries and {R*} to mark the repeat portion (distinct from the psalm flexa *):

{Rsp|}
{R.} Mostraci Signore,
{R*} la tua misericordia.

{V.} E donaci la tua salvezza,
{R*} la tua misericordia.

{Gloria}

{R.} Mostraci Signore,
{R*} la tua misericordia.
{|Rsp}

Gloria Patri

This avoids duplicating the Gloria Patri text in every psalm file. The app inserts the correct locale-specific doxology automatically.

Intercessions with Roles

Intercessions distinguish celebrant, assembly, and petition parts using {Int|} / {|Int} block boundaries and semantic role markers:

{Int|}
{C.} Supplichiamo Dio nostro Padre:
{A.} Custodisci il tuo popolo, Signore.

{C.} Dio, che hai promesso al tuo popolo un germoglio di giustizia,
{P.} conserva pura e santa la tua Chiesa.

{C.} Apri il nostro cuore all'ascolto della tua parola,
{P.} rendici forti e irreprensibili nella testimonianza della fede.
{|Int}

Biblical References

Use {Ref ...} to tag explicit biblical references, rendered in superscript rubric style:

{Ref Gen 1, 1-3}
{Ref Sal 62, 2-9}

Hour Structure (Composite Documents)

For self-contained documents representing a complete liturgical hour, use {Hour|} / {|Hour} to wrap the entire hour and {Sect|} to mark sections:

{Hour| Lauds}

{Sect| Introduction}
{V.} O Dio, vieni a salvarmi.
{R.} Signore, vieni presto in mio aiuto.
{Gloria}

{Sect| Psalm 56}
{Ant|}
Pietà di me, o Dio, in te mi rifugio.
{|Ant}
Pietà di me, o Dio, *
  in te mi rifugio...
{Gloria}
{Ant|}
Pietà di me, o Dio, in te mi rifugio.
{|Ant}

{Sect| Reading Is 66, 1-2}
{Ref Is 66, 1-2}
Così dice il Signore...

{Sect| Intercessions}
{Int|}
{C.} Supplichiamo Dio:
{A.} Custodisci il tuo popolo.
{|Int}

{Sect| Prayer}
O Dio, creatore e redentore...

{|Hour}

All Liturgical Markers Reference

RPL Replacement System

The RPL (Replacement) system allows texts to include placeholders that are filled dynamically based on the liturgical calendar. RPL files live in the RPL/ directory.

File Naming

RPL File Format

Each line contains a token-replacement pair, separated by |:

@MEMORIA@|sant'Antonio abate
@COMMEMORAZIONE@|nella memoria di sant'Antonio

In your BMD texts, use the token (e.g., @MEMORIA@) where the replacement should appear. The app substitutes the token with the replacement at runtime based on the current date.

Fragment Frontmatter

Individual text files can include optional YAML frontmatter between --- delimiters:

---
title: Psalmus 22
work: Psalterium
language: lat
script: latin
---

# Psalmus 22
Dominus pascit me...

Language & Script Codes

Use ISO 639-3 codes for language identification. Common codes for Horatio packs:

Bundled Fonts

Horatio bundles Noto Sans font variants for the following scripts. If your pack uses a script not listed here, specify the required font in required_fonts.

Building a Pack

Step 1: Create the Directory Structure

mkdir my-pack
mkdir my-pack/texts

Step 2: Write manifest.json

Start with the manifest template above. Set your id, language, script, and other metadata.

Step 3: Create Text Fragments

Write your texts as .bmd files using the BMD markup. Place them in the texts/ directory.

Step 4: Build codes_map.json

Create a mapping entry for each text fragment. The file path is relative to the pack root.

Step 5: Package as .htx

# From the pack directory:
cd my-pack
zip -r ../my-pack.htx manifest.json codes_map.json texts/

Step 6: Install and Test

Import the .htx file in Horatio using the Pack Manager's "Import .htx" button. Verify that:

• The pack appears in the Pack Manager with correct metadata
• All fragments are readable and correctly formatted
• RTL text direction works correctly (if applicable)
• Special characters and diacritics render properly
• Full-text search indexes the content

Submission Checklist

Before sharing your pack, verify:

• manifest.json has a unique id, correct language (ISO 639-3), and script
• codes_map.json maps every text file
• All file paths in codes_map actually exist in the archive
• fragment_count matches the actual number of entries
• Text files use UTF-8 encoding
• BMD markup is well-formed (matched {}, //, $$, ^^)
• text_direction is "rtl" for Hebrew, Arabic, Syriac
• BLAKE3 checksum is computed and set in checksum_blake3
• The .htx file opens successfully in Horatio's Pack Manager