scripture-guide

Scripture Guide

A multilingual scripture reference parser for looking up, generating, and detecting scripture references across multiple religious canons.

scripture.guide

Features

• Parse references - Convert "John 3:16" to verse IDs
• Generate references - Convert verse IDs back to human-readable strings
• Detect references - Find and link scripture references in text
• 12 languages - English, Korean, German, French, Russian, Vietnamese, Swedish, Tagalog, Japanese, Turkish, Slovenian, Esperanto
• Multiple canons - Bible, LDS, RLDS, Hindu, Buddhist, Islamic texts
• Context-aware detection - Recognizes implied references like "v. 16" and "vv. 17-18"

Installation

npm install scripture-guide

Quick Start

import { lookupReference, generateReference, detectReferences } from 'scripture-guide';

// Parse a reference to verse IDs
lookupReference('John 3:16');
// { query: 'John 3:16', ref: 'John 3:16', verse_ids: [26137] }

// Generate a reference from verse IDs
generateReference([26137, 26138, 26139]);
// 'John 3:16-18'

// Detect and link references in text
detectReferences('Read John 3:16 today.', (ref, ids) => `<a href="/v/${ids[0]}">${ref}</a>`);
// 'Read <a href="/v/26137">John 3:16</a> today.'

API Reference

lookupReference(query, options?)

Parse a scripture reference string into verse IDs.

lookupReference('Mt 5:3-12');
// { query: 'Mt 5:3-12', ref: 'Matthew 5:3-12', verse_ids: [23239, 23240, ...] }

lookupReference('Genesis 1:1', 'ko');  // string options = language
// { query: 'Genesis 1:1', ref: '창세기 1:1', verse_ids: [1] }

lookupReference('1 Nephi 3:7', { language: 'en', canon: 'lds' });
// { query: '1 Nephi 3:7', ref: '1 Nephi 3:7', verse_ids: [23152] }

Parameters:

Name	Type	Description
query	string	Scripture reference to parse
options	string | object	If string, treated as language code
options.language	string	Language code
options.canon	string	Canon: 'lds', 'rlds', etc.

Backward Compatibility: The old 3-parameter signature lookupReference(query, language, config) is deprecated but still supported.

Returns:

{
  query: string;        // Original input
  ref: string;          // Normalized reference
  verse_ids: number[];  // Verse ID array
  error?: string;       // Error message if failed
}

generateReference(verse_ids, options?)

Convert verse IDs to a formatted reference string.

generateReference([1, 2, 3]);
// 'Genesis 1:1-3'

generateReference([26137], 'de');  // string options = language
// 'Johannes 3:16'

generateReference([1, 2, 3, 10, 11], { language: 'en', canon: 'lds' });
// 'Genesis 1:1-3, 10-11'

Parameters:

Name	Type	Description
verse_ids	number[]	Array of verse IDs
options	string | object	If string, treated as language code
options.language	string	Language code
options.canon	string	Canon: 'lds', 'rlds', etc.

Backward Compatibility: The old 3-parameter signature generateReference(ids, language, options) is deprecated but still supported.

detectReferences(content, callback?, options?)

Find scripture references in text and optionally transform them.

// Default: wrap in brackets
detectReferences('See Matthew 5:3-12 and John 3:16.');
// 'See [Matthew 5:3-12] and [John 3:16].'

// Custom callback
detectReferences('Read John 3:16.', (ref, ids) => {
  return `<a href="/bible/${ids.join(',')}">${ref}</a>`;
});

// Context-aware: detects "v. 16" from surrounding context
detectReferences('In John 3, Jesus explains (v. 16) that God loved the world.');
// Detects 'John 3:16'

Parameters:

Name	Type	Description
content	string	Text containing references
callback	function	(query, verseIds) => string
options.language	string	Language code
options.contextAware	boolean	Enable context detection (default: true)
options.enableImpliedBooks	boolean	Detect bare verse numbers (default: true)

setLanguage(language)

Set the default language for all subsequent calls.

import { setLanguage, lookupReference } from 'scripture-guide';

setLanguage('ko');
lookupReference('요한복음 3:16');
// Works in Korean

setCanon(canon)

Set the default canon for all subsequent calls.

import { setCanon, lookupReference } from 'scripture-guide';

setCanon('lds');    // LDS Standard Works (default)
setCanon('rlds');   // RLDS/Community of Christ

Supported Reference Formats

Format	Example
Simple verse	Exodus 1:1
Chapter only	Genesis 2
Verse range	Exodus 20:1-10
Split verses	Exodus 20:5,10
Split chapters	Genesis 1,3
Chapter range	Exodus 3-5
Multi-chapter range	Exodus 1:5-4:3
Multi-book range	Genesis 30—Exodus 2
Compound references	Exodus 5:1; Leviticus 6:2
Abbreviations	Mt 2:5, Mk 3, 1 Jn 1:5
Entire book	Genesis

Language Support

Code	Language	Example Reference
en	English	John 3:16
ko	Korean	요한복음 3:16
de	German	Johannes 3:16
fr	French	Jean 3:16
ru	Russian	Иоанна 3:16
jp	Japanese	ヨハネによる福音書 3:16
vn	Vietnamese	Giăng 3:16
tr	Turkish	Yuhanna 3:16
swe	Swedish	Johannes 3:16
tgl	Tagalog	Juan 3:16
slv	Slovenian	Janez 3:16
eo	Esperanto	Johano 3:16

Canons

Canon	Description
bible	Protestant Bible (66 books)
lds	LDS Standard Works (Bible + Book of Mormon + D&C + Pearl of Great Price)
rlds	RLDS/Community of Christ canon
hindu	Hindu scriptures
buddhist	Buddhist texts
islam	Islamic texts

Verse IDs

Verse IDs are sequential integers starting from Genesis 1:1.

Reference	Verse ID
Genesis 1:1	1
Genesis 1:2	2
Genesis 50:26	1533
Exodus 1:1	1534
Malachi 4:6	23145
Matthew 1:1	23146
John 3:16	26137
Revelation 22:21	31102

Use verse IDs to query your scripture database:

SELECT * FROM verses WHERE verse_id IN (26137, 26138, 26139);

Configuration

Custom Canon Data

Canon data is stored in data/canons/{canon}/{language}.yml:

canon: bible
language: en

books:
  genesis:
    name: Genesis
    pattern: "[Gg]enesis"
    alt: [Gen, Gn]
  exodus:
    name: Exodus
    pattern: "[Ee]xodus"
    alt: [Exod, Ex]

Structure Data

Verse counts per chapter are in data/structure/{canon}.yml:

genesis: [31, 25, 24, 26, 32, 22, 24, ...]  # verses per chapter
exodus: [22, 25, 22, 31, 23, 30, 25, ...]

Function Aliases

For convenience, functions have shorter aliases:

Full Name	Aliases
lookupReference	lookup, parse, read, ref2VerseId
generateReference	generate, gen, ref, verseId2Ref
detectReferences	detect, detectRefs, linkRefs
setLanguage	lang, setLang
setCanon	canon

Build

npm run build       # Build dist files
npm run test:jest   # Run tests

License

ISC

Author

KC Kern - kckern