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 IDslookupReference('John 3:16');// { query: 'John 3:16', ref: 'John 3:16', verse_ids: [26137] }// Generate a reference from verse IDsgenerateReference([26137,26138,26139]);// 'John 3:16-18'// Detect and link references in textdetectReferences('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 bracketsdetectReferences('See Matthew 5:3-12 and John 3:16.');// 'See [Matthew 5:3-12] and [John 3:16].'// Custom callbackdetectReferences('Read John 3:16.',(ref,ids)=>{return`<a href="/bible/${ids.join(',')}">${ref}</a>`;});// Context-aware: detects "v. 16" from surrounding contextdetectReferences('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: biblelanguage: enbooks:
genesis:
name: Genesispattern: "[Gg]enesis"alt: [Gen, Gn]exodus:
name: Exoduspattern: "[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 chapterexodus: [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