BSB Bible PDF Toolkit

Generate custom PDFs and EPUBs from the Berean Standard Bible (BSB) source files.

Mission

This project exists to help Christian technologists, designers, publishers, and builders download, study, remix, and share Scripture resources in creative new ways. The BSB text has been dedicated to the public domain, so the goal here is to make practical tooling and example editions that encourage more people to distribute Scripture freely.

This is an unofficial community toolkit. It is not affiliated with or endorsed by the Berean Bible Translation Committee, Bible Hub, or the other BSB project partners.

Download and Share

If you only want the current generated Bible PDFs, download them directly:

If GitHub Releases are available for this repo, prefer the latest release for versioned PDFs and SHA-256 checksums.

You are encouraged to copy, share, print, adapt, and build new Scripture tools from these resources. Keep the BSB text verbatim if you use the Berean name; if you make textual changes, present the result as your own derivative rather than as an official Berean Bible text.

Build Your Own Edition

# Create and activate an isolated environment
python -m venv .venv
source .venv/bin/activate

# Install dependencies
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

# Build the primary PDF draft from the official fixed-layout BSB PDF
python design_bsb.py

Commands use python for readability; use python3 on systems where python is not available.

After installing the package in editable mode, you can use the console commands directly:

python -m pip install -e .
bsb-design --qa-only --verify
bsb-reflow-pdf drafts/primary/source/engbsb_usfm.zip my-single-column.pdf --font-dir fonts --columns 1

The current prototyping flow has one primary draft. It uses https://bereanbible.com/bsb-book-9.pdf as the visual baseline, adds route.bible annotations, then redraws the fixed layout with Lexend.

To rebuild from a freshly downloaded source:

python design_bsb.py --refresh-source

To use a local BSB PDF instead of downloading:

python design_bsb.py --source path/to/bsb-book-9.pdf

To verify the current generated artifacts and refresh the visual comparison sheets without rebuilding:

python design_bsb.py --qa-only --verify --compare

--qa-only must be paired with --verify, --compare, or both.

Spacing can be tuned without changing the source layout:

python design_bsb.py --weight-profile calm --font-scale 0.86 --footer-scale 0.80 --footer-shift 9 --body-gray 0.08 --footer-gray 0.34 --structural-gray 0.03

The primary draft uses the calmer Lexend profile by default:

An exploratory single-column reflow is also available:

PYTHONPATH=src python -m bsb_pdf_toolkit.generate_reflow_pdf \
    drafts/primary/source/engbsb_usfm.zip \
    drafts/primary/bsb-single-column-draft.pdf \
    --font-dir fonts --columns 1

Common single-column tuning flags include --single-margin-x, --single-body-size, --single-body-leading, --single-book-title-font, --single-dropcap-size, --single-dropcap-padding, --single-dropcap-protected-lines, --single-verse-size, and --single-verse-baseline-shift. The default book title face is Lexend-Bold. Both PDF generators accept --release-stage; local builds default to Draft, while the delivery workflow stamps packaged release copies with a semantic version label such as Version 0.0.1.

To generate visual QA sheets for judging the current typography against the official source:

PYTHONPATH=src python -m bsb_pdf_toolkit.compare_renders

To verify the generated PDF artifacts structurally:

PYTHONPATH=src python -m bsb_pdf_toolkit.verify_artifacts

Add --strict-fingerprints when you need the current SHA-256 fingerprints to match exactly. The default verifier enforces stable semantic fingerprints and reports raw PDF hashes.

BSB JSON API

In addition to the PDF/EPUB tooling, this repo publishes a free, structured BSB JSON API that serves the public-domain Berean Standard Bible over HTTPS with no API key and no rate limit. The API is a Cloudflare Worker using a 4-tier cache-aside pattern: edge cache, then an R2 bucket, then the Arweave permanent origin (api_bsb undername on the scripture ArNS name), and finally a 503 if every tier is exhausted. All Bible reference parsing is delegated to grab-bcv.

Quick start:

# Local Worker on port 8787
cd api && npm install && npx wrangler dev --port 8787

# Fetch a verse
curl 'http://localhost:8787/v1/verse/JHN.3.16'

# Fetch a passage (URL-encode spaces)
curl 'http://localhost:8787/v1/passage/John%203:16-18'

# Filter cross-references by source (tsk, bsb-footnote, acai, theographic)
curl 'http://localhost:8787/v1/crossrefs/GEN.1.1?source=tsk'

The /v1/ paths are frozen forever; schema changes go to /v2/. Responses are CORS-enabled with Cache-Control: public, max-age=31536000, immutable and an X-Origin header indicating which cache tier served the request (edge, r2, or arweave).

See dataset/README.md for the full JSON schema, OSIS reference format, source-filtering docs, and Python/JavaScript quickstarts. Example consumers live in dataset/examples/.

How to Help

Ideas that fit this repo's mission:

• improve readable, printable BSB layouts;
• build web, mobile, EPUB, print, or study-tool experiments around the public-domain BSB;
• improve route.bible linking, OSIS indexing, and reader navigation;
• add clear documentation so churches, ministries, and developers can reuse the work;
• share examples of creative Scripture distribution projects inspired by this toolkit.

Please keep changes reproducible, document generated artifacts, and run the structural verifier before proposing release-affecting changes.

CI/CD Asset Delivery

This repo includes a GitHub Actions workflow at .github/workflows/deliver-assets.yml that verifies the committed PDF artifacts, stamps release copies as Version, and packages them with SHA-256 checksums. Manual dispatch runs can also upload the generated PDFs and checksums to a GitHub Release, publish the variants to itch.io through Butler, and deploy the web-reader bundle to Permaweb.

Configure these repository secrets before enabling manual delivery targets:

The itch.io target is configured in the workflow as ITCH_TARGET.

The workflow publishes two Butler channels:

The workflow also uploads each variant as an individually downloadable GitHub Actions artifact:

When a manual run sets dry_run to false, the workflow creates or updates the GitHub Release tagged v<release_version> and uploads:

Run it manually from GitHub Actions with the default dry_run: true to verify/package without publishing. Set dry_run: false only when you are ready to publish. The workflow defaults to version 0.0.1; provide release_version when dispatching manually to publish another semantic version.

Legacy/Utility Commands

# Legacy downloader utility
PYTHONPATH=src python -m bsb_pdf_toolkit.download_bsb --book 9

# Extract text and structure
PYTHONPATH=src python -m bsb_pdf_toolkit.extract_bsb --input bsb-book-9.pdf --output bsb-book-9.json

# Generate a custom PDF
PYTHONPATH=src python -m bsb_pdf_toolkit.customize_bsb --input bsb-book-9.pdf --output my-bsb.pdf \
    --font-size 11 --margin 36 --no-footnotes

# Add route.bible links to all chapter headings
PYTHONPATH=src python -m bsb_pdf_toolkit.add_route_links bsb-book-9.pdf bsb-linked.pdf

Two Paths: PDF vs EPUB

This toolkit supports both PDF and EPUB output. Choose based on your needs:

Recommendation: Use EPUB for font customization. Use PDF for print-ready output with verse-range links.

---

EPUB Path (Recommended for Font Changes)

The EPUB is HTML-based, so font changes are trivial and text reflows automatically. No layout breakage.

# Download the BSB EPUB
# https://bereanbible.com/bsb.epub

# Customize with Lexend fonts + add route.bible links
PYTHONPATH=src python -m bsb_pdf_toolkit.customize_epub bsb.epub bsb-lexend.epub \
    --font-dir fonts/ --add-links

# Output: bsb-lexend.epub with embedded Lexend fonts and clickable headings

The script:

1. Extracts the EPUB
2. Embeds all Lexend font variants (Regular, Medium, Bold, etc.)
3. Updates CSS to use font-family: "Lexend"
4. Adds route.bible/{book}.{chapter} links to every <p class="hdg"> heading
5. Re-packages the EPUB

EPUB Customization Options

---

PDF Path (Best for Print + Verse-Range Links)

Add route.bible Links

add_route_links.py detects every BSB section heading by font heuristics and inserts a clickable link to the exact OSIS verse range on https://route.bible. It adds new route.bible annotations; it does not rewrite existing URI annotations such as Bible reference links.

# Add verse-range links to every heading in a BSB PDF
PYTHONPATH=src python -m bsb_pdf_toolkit.add_route_links bsb-book-9.pdf bsb-linked.pdf

# Works on any BSB PDF, including combined or customized ones
PYTHONPATH=src python -m bsb_pdf_toolkit.customize_bsb --input bsb-book-9.pdf --output temp.pdf --no-footnotes
PYTHONPATH=src python -m bsb_pdf_toolkit.add_route_links temp.pdf final.pdf

Verse-Range Links

Each heading is linked to its specific verse range rather than the full chapter:

• The Creation → https://route.bible/Gen.1.1-2
• The First Day → https://route.bible/Gen.1.3-5
• The Fourth Day → https://route.bible/Gen.1.14-19
• Hannah's Prayer → https://route.bible/1Sam.2.1-11
• The LORD Calls Samuel → https://route.bible/1Sam.3.1-14

The script detects verse numbers by their small Cambria-Bold font (~6.8pt) and tracks them through the two-column layout to compute exact start/end verses for every heading.

Change Font to Lexend (PDF)

⚠️ Warning: PDF is a fixed-layout format. The font changer preserves the original line breaks and baselines, but Lexend has different metrics from Cambria.

# Convert to Lexend (requires fonts in ./fonts/ directory)
PYTHONPATH=src python -m bsb_pdf_toolkit.change_font input.pdf output.pdf

# The fonts/ directory should contain:
#   Lexend-Regular.ttf
#   Lexend-Bold.ttf
#   Lexend-Medium.ttf
#   Lexend-SemiBold.ttf
#   (and optionally others)

Correct workflow for PDF:

# 1. Add links first (detection needs original font names)
PYTHONPATH=src python -m bsb_pdf_toolkit.add_route_links bsb-book-9.pdf bsb-linked.pdf

# 2. Then change font while preserving existing URI annotations
PYTHONPATH=src python -m bsb_pdf_toolkit.change_font bsb-linked.pdf bsb-lexend.pdf

For perfect font rendering, use the EPUB path instead.

---

What You Can Customize

BSB Book Numbers

Examples

# Personal study Bible — larger font, no footnotes
PYTHONPATH=src python -m bsb_pdf_toolkit.customize_bsb --input bsb-book-9.pdf --output study-bible.pdf \
    --font-size 12 --margin 48 --no-footnotes

# Combine multiple books into one PDF
PYTHONPATH=src python -m bsb_pdf_toolkit.customize_bsb --books 1,2,3 --output pentateuch.pdf

# Extract just a chapter range (pages 100–200)
PYTHONPATH=src python -m bsb_pdf_toolkit.customize_bsb --input bsb-book-9.pdf --range 100-200 \
    --output 1sam-ch7-15.pdf

# Generate a grayscale pocket edition
PYTHONPATH=src python -m bsb_pdf_toolkit.customize_bsb --input bsb-book-9.pdf --output pocket.pdf \
    --page-size 5x8 --grayscale --font-size 9

# EPUB: Lexend font + route.bible links
PYTHONPATH=src python -m bsb_pdf_toolkit.customize_epub bsb.epub bsb-lexend.epub \
    --font-dir fonts/ --add-links

License

The Berean Bible and Majority Bible texts were dedicated to the public domain under CC0 on April 30, 2023. The official terms say all uses are freely permitted; attribution is appreciated but not required. See https://berean.bible/terms.htm.

Toolkit source code is MIT licensed; see LICENSE. Bundled Lexend font files are distributed under the SIL Open Font License 1.1; see fonts/OFL.txt. Generated documents may embed the fonts under the OFL, but the font files must not be sold by themselves.

Additional attribution and project notices are collected in NOTICE.