lwoodard/Custom-Local-Bible-Ref
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README.md

Browse Source
This commit is contained in:
Caleb Campbell
2025-07-17 07:43:38 +10:00
committed by GitHub
parent cff0a4620c
commit 97fc7927c8
1 changed files with 17 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
README.md
View File

@@ -6,11 +6,11 @@ Quickly and easily reference Bible passages stored locally in your Obsidian vaul
### Inspiration
This plugin takes heavy inspiration from the [Bible Reference](https://github.com/tim-hub/obsidian-bible-reference) and [Bible Linker](https://github.com/kuchejak/obsidian-bible-linker-plugin) plugins - please check them out! I've been using the *Bible Reference* plugin for a while (which has been great) and I love the simplicity of referencing passages using the `--` prefix. I also loved the idea of storing a Bible locally because then I could reference Bible passages even when I'm offline, as well as use my vault Bible for reading. Unfortunately, the markdown format of the *Bible Linker* local Bible is not great for reading, and I prefer the simplicity of using the `--` prefix to fetch Bible passages. There's also some referencing limitations in the *Bible Reference* plugin and occasionally some odd additions to passages returned from the [Boll's Life](https://bolls.life/) API. So, this is an amalgamation of those two plugins.
This plugin takes heavy inspiration from the [Bible Reference](https://github.com/tim-hub/obsidian-bible-reference) and [Bible Linker](https://github.com/kuchejak/obsidian-bible-linker-plugin) plugins - please check them out! I've been using the *Bible Reference* plugin for a while (which has been great) and I love the simplicity of referencing passages using the `--` prefix. I also loved the idea of storing a Bible locally because then I can reference Bible passages even when I'm offline, as well as use my vault Bible for reading. Unfortunately, the markdown format of the *Bible Linker* local Bible is not great for reading, and I prefer the simplicity of using the `--` prefix to fetch Bible passages. There's also some referencing limitations in the *Bible Reference* plugin and occasionally some odd additions to passages returned from the [Boll's Life](https://bolls.life/) API. So, this is an amalgamation of those two plugins.
### Getting Started
To start with, you will need to create a Bible in your own vault. Some instructions on this can be found [below](#bible-markdown-format) (this plugin uses a different markdown format to *Bible Linker*). Once you've done that, open up the *Local Bible Ref* settings and fill out the *Bibles Path* and *Default Version Shorthand* fields. Then, to use the plugin, simply open a new note and use the `--` reference prefix to grab a passage of scripture. There are also additional options (similar to terminal command options) you can provide to the reference to indicate which version to use and what markdown format to display the passage in. More information can be found [below](#usage).
To start with, you will need to format a Bible for your own vault. Some instructions on this can be found [below](#bible-markdown-format) (this plugin uses a different markdown format to *Bible Linker*). I've also already formatted the Public Domain World English Bible so you can [download](https://github.com/camelChief/markdown-webp) that and just get started. Once you've done that, open up the *Local Bible Ref* settings and fill in at least the *Bibles Path* field. Then, to use the plugin, simply open a new note and use the `--` reference prefix to grab a passage of scripture. There are also additional options (similar to terminal command options) you can provide to the reference to indicate which version to use and what markdown format to display the passage in. More information can be found [below](#usage).
![localBibleRef1](https://github.com/user-attachments/assets/b8b5440b-8f47-4462-987e-a52791d758be)
@@ -34,22 +34,25 @@ The referencing syntax also allows for a lot of flexibility:
### Options
Local Bible Ref also allows you to provide a few options to a reference to specify which version you would like to use as well as what markdown format to use. Add an option to a reference by adding a `+` followed by the option (in any order): `--gen1:1-5+v:esv`
Local Bible Ref also allows you to provide a few options to a reference to specify which version you would like to use as well as what markdown format to use. Add an option to a reference by adding a `+` followed by the option (in any order): `--gen1:1-5+esv`
Syntax: `--<reference>[+<option>[:<value>]]...`
You can also pass multiple options by simply chaining them: `-- John 1:1 +quote +esv`
| Option | Value | Usage | Example | Live |
| ---------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ---- |
| `version`, `v` | `string` - the version code | Specifies what Bible version to use from the list of versions you have created in your vault. | `+version:niv` | ✔️ |
| `callout`, `c` | | Specifies that the passage should be displayed in [callout](https://help.obsidian.md/Editing+and+formatting/Callouts) format. | `+callout` | ❌ |
| `paragraph`, `p` | | Specifies that the passage should be displayed in a standard paragraph. | `+paragraph` | ❌ |
| `quote`, `q` | | Specifies that the passage should be displayed in [quote](https://help.obsidian.md/Editing+and+formatting/Basic+formatting+syntax#Quotes) format. | `+quote` | ❌ |
Syntax: `--<reference>[+<option>]...`
| Option | Usage | Example |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| `manuscript`, `m` | Specifies that the passage should be displayed in "manuscript" format (without chapter numbers, verse numbers or other formatting like newlines). | `--gen1:1+m` |
| `paragraph`, `p` | Specifies that the passage should be displayed in a standard paragraph. | `-- Genesis 1:1 +paragraph` |
| `quote`, `q` | Specifies that the passage should be displayed in [quote](https://help.obsidian.md/Editing+and+formatting/Basic+formatting+syntax#Quotes) format. | `-- John 1:1 +q` |
| `callout`, `c` | Specifies that the passage should be displayed in [callout](https://help.obsidian.md/Editing+and+formatting/Callouts) format. | `--john1:1+callout` |
| any other text, `niv` | Any other text besides the options listed above will be treated as a version code. | `--gen1:1+niv` |
## Bible Markdown Format
The Bible markdown format required for this plugin is slightly more complex than the format used for the *Bible Linker* plugin. I chose this particular format because it makes the Bible much nicer to read if you simply wanted to use your vault Bible for reading (as I do). It looks something like this:
![localBibleRef2](https://github.com/user-attachments/assets/e8f53757-81aa-4b77-a0e6-cbc6b2f1a4f4)
![localBibleRef2](https://github.com/user-attachments/assets/e5fc4ca1-bc9d-4fbb-b20c-e94c693d0660)
Most of the formatting shown here is unnecessary. You really only need to ensure your Bible adheres to the following:
@@ -58,15 +61,15 @@ Most of the formatting shown here is unnecessary. You really only need to ensure
- Chapters are named with the convention `<book name> <chapter>.md`: `Genesis 1.md`
- Chapters are grouped into folders with the full name of the book: `Genesis`
- Books are grouped into a folder with the version code of the Bible: `CSB`
- All versions are under the same folder
Doing things this way allows you to store and reference multiple different versions of the Bible:
![Pasted image 20240821090423](https://github.com/user-attachments/assets/378798fc-7f40-4862-99f9-8cbe97ca6301)
<img width="253" height="379" alt="image" src="https://github.com/user-attachments/assets/5804ceab-e69d-4b7f-a58d-3f9b5a89e3fc" />
Beyond that, everything else (section headings, footnotes, links) is optional. Be careful not to add odd characters or extra text in the verses, or they will show up when you reference them. Currently, referencing will ignore headings, footnotes and anything after a [horizontal rule](https://help.obsidian.md/Editing+and+formatting/Basic+formatting+syntax#Horizontal+rule).
Beyond that, everything else (section headings, footnotes, links) is optional. Be careful not to add odd characters or extra text in the verses, or they will show up when you reference them. Currently, referencing will ignore YAML frontmatter, headings, chapter numbers (any bolded digits), footnotes and anything after a [horizontal rule](https://help.obsidian.md/Editing+and+formatting/Basic+formatting+syntax#Horizontal+rule).
## Limitations
- Bible referencing **does not work** with the *Bible Linker* style of markdown Bible.
- Referencing does not yet support multiple passages: `Genesis 1:1; John 1:1`
- Currently, the passages will only display as a callout. I'll be adding paragraphs and quotes soon.