Markdown Bible Xref Tool

A Python utility that scans markdown notes containing Bible references then automatically populates a BibleCrossReferences YAML front matter property with every Bible reference found in the note body. The property is created in the YAML front matter if needed.

Originally designed to be used on an Obsidian vault containing Bible and sermon notes, and tested against a vault of ~900 Markdown files. The Bible Xref Tool will operate on a directory tree or a single file. If given an directory it will examine that directory and the tree under it. The app can be run in "dry run" mode where a log is made of the changes it would make during a live run.

Shell files are provided as examples, or can be modified to run the program.

In Obsidian, the Shell commands plugin can be used to call the script passing it the currently active file name so one file can be processed/updated from within Obsidian.

What It Does

Each Obsidian note that contains Bible references in its body text will have a BibleCrossReferences property added or updated in its YAML front matter, like this:

---
BibleCrossReferences:
  - Gen 1:1
  - John 3:16
  - Rom 8:28-30
---

• References are detected automatically from note body text using the pythonbible library
• Overlapping or duplicate references are merged and deduplicated
• References are sorted canonically by book, chapter, and verse
• Book names follow a consistent format (e.g., always Psalm, never Psalms)
• If Bible books are abreviated in the note, the full name is placed in the front matter.
• En dashes, em dashes, and double hyphens in reference ranges (common in Logos and NASB pastes) are normalized automatically
• The existing BibleCrossReferences block is excluded from re-scanning to avoid circular output
• All activity can be written to a persistent log file (yaml_bible_xref_log.md), appended on each run

Project Files

File	Purpose
yaml_bible_xref.py	Main script — processes a single .md file or an entire directory tree
reference_extractor.py	Parses Bible references from note body text
yaml_updater.py	Reads and writes YAML front matter using ruamel.yaml
logging_setup.py	Shared logging configuration; writes to yaml_bible_xref_log.md
run_yaml_bible_xref_vault.bat	Windows launcher — edit settings here and double-click to run
run_yaml_bible_xref_vault.sh	macOS launcher — edit settings here and run from Terminal
run_yaml_bible_xref_vault_ubuntu.sh	Ubuntu launcher — edit settings here and run from a terminal

Requirements and Installation

Requirements and step-by-step installation instructions — including Python version, third-party libraries (pythonbible and ruamel.yaml), and platform-specific notes — are documented in the comments at the top of each launcher file:

• Windows — see run_yaml_bible_xref_vault.bat
• macOS — see run_yaml_bible_xref_vault.sh
• Ubuntu — see run_yaml_bible_xref_vault_ubuntu.sh

Usage

Running Against a Vault (All Platforms)

1. Open the launcher file for your platform in a text editor
2. Set VAULT_PATH to the folder you want to process (can be your full vault root or any subfolder)
3. Set DEBUG_VALUE to test for a dry run (nothing is modified; activity is logged only) or leave it empty for a real run
4. Save the file and run it

Command-Line Usage

The script can also be called directly:

# Process an entire vault directory
python3 yaml_bible_xref.py --path /path/to/vault

# Process a single file
python3 yaml_bible_xref.py --path /path/to/note.md

# Dry run (no files modified)
python3 yaml_bible_xref.py --path /path/to/vault --debug test

# All options
python3 yaml_bible_xref.py \
    --path /path/to/vault \
    --logdir /path/to/log/folder \
    --logging on \
    --backup on \
    --debug test

CLI Options

Option	Values	Default	Description
--path	file or directory path	(required)	File or vault folder to process
--logdir	directory path	script's own folder	Where yaml_bible_xref_log.md is written
--logging	on / off	on	Enable or disable log file output
--backup	on / off	off	Save a .md.bak copy of each file before modifying it
--debug	test / (empty)	(empty)	test = dry run; empty = real run

Dry Run (Recommended First Step)

Before running against your full vault for the first time, do a dry run:

• Set DEBUG_VALUE=test (Windows) or DEBUG_VALUE="test" (Mac/Ubuntu) in the launcher
• The script will scan all files and log what it would change — without touching anything
• Review yaml_bible_xref_log.md to verify the output looks correct
• Then set DEBUG_VALUE back to empty and run for real

Log File

All activity is written to yaml_bible_xref_log.md in the launcher's folder (or whatever --logdir points to). The log is always appended, never overwritten, so you retain a full history of every run. Each run records:

• Start and stop time
• Every file modified and what changed
• Any Bible reference fragments that could not be parsed (with the failing text narrowed down via recursive bisection)
• A summary count of files processed, modified, and skipped

Notes and Limitations

• It is estimated that it will traverse a tree 20 directories deep, but this has not been verified.

• The script is designed for Obsidian vaults where notes are standard Markdown files with YAML front matter

• pythonbible does not recognize every possible Bible reference format; ambiguous or malformed references are logged as warnings and skipped rather than causing the run to fail

• The .md.bak backup option (--backup on) is a simple testing aid — it overwrites any previous .bak on each run and is not a versioned backup system

Dependencies

• pythonbible — Bible reference parsing and normalization
• ruamel.yaml — YAML front matter read/write with formatting preservation