opm.toml

[project]
# Additional Python import paths for local extension modules.
# Paths are resolved relative to this config file.
# pythonpath = ["."]

[transform]
# Default ODD for every output mode (compiled on demand into the user cache).
# Per-type tables may override with their own odd = "...".
# odd = "odd/my-customisation.odd"

# XPath extension modules loaded into the tp: namespace.
xpath_extensions = [
    "opm.runtime.common_xpath_functions"
    # "extensions.my_functions",
]

# XML documents available to XPath doc().
# Paths are resolved relative to this config file; doc("...") lookups resolve
# relative to the main XML input document URI.
# documents = [
#     "data/authority.xml",
#     "data/lookup.xml",
# ]

# Namespace prefixes for XPath written inside the ODD.
# Merged over the ODD root's own xmlns declarations, and these win on a clash.
# Binding a prefix here rather than in the ODD matters most for variables: a
# prefix inside an attribute value is not an XML name, so it should not depend
# on which ODD is loaded.
#
# [transform.namespaces]
# global = "http://teipublisher.com/global"

# Values for XPath variables, grouped by the prefix declared above — that prefix
# plus the local name is how the ODD refers to one: $global:register-root. A
# namespace URI works as the key too, and scalars directly under
# [transform.variables] are variables in no namespace ($name).
# Values keep their TOML type — quote strings, leave booleans bare. (A quoted
# "false" is a non-empty string, which XPath treats as true.)
# These five are the ones teipublisher.odd reads:
#
# [transform.variables.global]
# register-root = "urn:registers"   # collection() of person/place records
#
# A model whose variable or collection is not configured falls back to rendering
# the element itself, so leaving these unset is safe.

# Documents reachable from XPath collection(), keyed by the URI used in the call.
# `uri` is an opaque key, matched verbatim after resolution — opm never reads
# from it, the files come from `documents` below. It only has to be the same
# string the ODD passes to collection(), so a urn: keeps that plain. Any
# absolute URI works, including the collection path an eXist app uses
# (/db/apps/myapp/data/registers), which lets a ported ODD stay unchanged; a
# relative URI is rejected, since it would resolve against each source document
# in turn. Repeat the block for further collections — repeating a uri merges the
# members rather than replacing them. Members are also registered for
# doc()/id(), which fn:id needs to resolve.
#
# [[transform.collections]]
# uri = "urn:registers"
# documents = [
#     "data/registers/persons.xml",
#     "data/registers/places.xml",
# ]

# Base rules compiled into the ODD stylesheet for every output type, replacing
# the packaged defaults (popovers, column breaks, margin notes). Not the place
# for design CSS — list that under [chunking] assets.
# css = "styles/default-styles.css"

[transform.web]
# Optional override: odd = "odd/web-only.odd"
# Jinja2 template used to wrap full-document HTML output.
# template = "templates/default.html.j2"
# Enable TEI Publisher web-component output mode by default.
webcomponents = false

# The pb-components bundle URL is an ordinary template value with a pinned
# default, not a setting of its own. Serve it yourself, or pin another version:
# [transform.web.context]
# webcomponents_url = "https://cdn.jsdelivr.net/npm/@teipublisher/pb-components@3.6.8/dist/pb-components-bundle.js"

# Free-form values handed to every Jinja2 template as `context`, e.g.
# {{ context.site_name }}. TOML types are preserved, so booleans, numbers,
# arrays and sub-tables all arrive intact. Templates only — XPath never sees
# these; that is what [transform.parameters] is for.
# [context]
# site_name = "TEI Publisher"
# show_downloads = true

# A per-output-type overlay on [context], applied for that type only.
# [transform.typst.context]
# paper = "a5"

[transform.docx]
# Optional override: odd = "odd/docx-only.odd"
# Word style template used for DOCX output.
# template = "templates/corporate.docx"

[transform.typst]
# Optional override: odd = "odd/typst-only.odd"
# Typst document-shell template used for Typst output.
# template = "templates/book.typ.j2"      # TEI (ilm)
# template = "templates/docbook.typ.j2"   # DocBook (ilm + UI/callout classes)

[chunking]
# ODD compiled on demand. Falls back to [transform].odd / packaged default when omitted.
# odd = "odd/my-customisation.odd"

# XPath expression selecting chunk root elements.
# xpath = "//text/body/div"
# When using --format pb-view, the xpath passed by the dynamic pb-view may differ from the xpath used by opm.
# Specify the expected dynamic xpath here, so lookups will pass.
# xpath_dynamic = "//text/body/div"

# Python callable for custom chunk selection logic.
# Enabled so `opm chunk examples/tei-test.xml` works from a clone.
selector = "opm.navigation.tei_div_chunks"
# selector = "opm.navigation.tei_pb_chunks"  # view=page: one chunk per tei:pb
# selector = "opm.navigation.dbk_section_chunks"

# Maximum depth used by built-in navigation selectors.
depth = 2

# Output directory for chunk files.
output_dir = "chunks"

# Jinja2 template for chunk pages.
# template = "templates/chunk.html.j2"

# URL pattern for cross-chunk links.
# Available placeholders: {file}, {stem}, {anchor}.
# link_pattern = "{file}#{anchor}"

# pb-view lookup mode, e.g. "div", "page", or "single".
# view = "div"

# Optional map parameter included in pb-view lookup keys.
# map = "default"

# Optional user parameters emitted into pb-view lookup keys as user.<key>=<value>.
# [chunking.parameters]
# lang = "en"

# Document path subdirectory for --format pb-view output.
# doc_path = "letters"

# Fragment definitions used by chunking.
# [[chunking.fragments]]
# name = "toc"
# scope = "global"
# xpath = "//text/body"
# odd = "odd/my-customisation.odd"
# parameters = { mode = "toc" }
#
# [[chunking.fragments]]
# name = "notes"
# scope = "per-chunk"
# xpath = ".//note"
# odd = "odd/my-customisation.odd"
# mode = "markdown"

[index]
# Rollup tuning for `opm index`, which emits JSONL records for a search index.
# max_chars = 1500   # split a passage longer than this
# min_chars = 40     # drop units shorter than this; a bare heading is noise
# overlap = 1        # records of context carried into the next part on a split

# Which JSON records open a passage. Omit this to keep the default: titled
# divisions (a `section` behaviour, or any record that carries a heading).
# Declaring any unit *replaces* that walk.
#
# [[index.units]]
# name = "heading"
# behaviours = ["heading"]
# emit = false       # label the next passage; do not emit a record
# min_chars = 1
#
# [[index.units]]
# name = "paragraph"
# behaviours = ["paragraph"]


# Material pulled out of a passage. Records are selected by `elements`,
# `behaviours` or `models` — the three handles a JSON record carries — or by
# `fragment`, which names a [[chunking.fragments]] entry and copies that
# page chrome onto every record (stripped to a scalar).
#
# metadata = true (the default) copies the matched text onto the passage as
# a list of strings you can facet on, and leaves it in the prose:
#
# [[index.fields]]
# name = "persons"
# elements = ["persName"]
#
# [[index.fields]]
# name = "breadcrumb"
# fragment = "breadcrumbs"
#
# metadata = false makes each match a record of its own, tagged kind = "note"
# and carrying the id of the passage it came from — so whether notes reach the
# index stays a filter at load time. The text then leaves the passage it
# annotates, unless inline = true keeps it in both places:
#
# [[index.fields]]
# name = "note"
# elements = ["note"]
# metadata = false
# inline = false