Quran Key

Toolkit for Islamic studies and Quran research with verse lookup, multi-source tafsir, and reflection notes.

See the roadmap and vault-note schema for planned surah/ayah note workflows and the structure of plugin-generated notes.

---

Features

• Contextual Verse Extraction: Auto-detects quotes, braces {query}, selections, and shorthand citations (e.g., [البقرة:255] or البقرة 255-257) directly from the cursor line.
• Snippet Trimming & View Toggle: Extract exact word-ranges (من-إلى) or invoke extraction consecutively to toggle between full ayah and snippet views.
• Multi-Source Tafsir Engine: Fetch commentary across 40+ classical and contemporary tafsir books with custom source support.
• Unified Ayah Journaling: Record reflections, benefits, and notes under dedicated headings inside a single unified note per ayah, or configure separate category folders.
• Surah & Ayah Notes: Open a complete surah as continuous mushaf-style text, then click an ayah marker to lazily create and open its note.
• Related Verse Linking: Group and cross-link semantically related ayahs together via frontmatter metadata.
• Typography & Display Lab: Compare verified Uthmani text/font candidates and ayah-ending markers before choosing the production rendering.
• Footnote & Utility Commands: Convert inline citations into markdown footnotes, strip tashkeel, or clean references with single hotkeys.

Quran text source

The bundled Quran corpus is based on Tanzil Quran Text (Uthmani, Version 1.1). Production rendering uses one fixed display: the canonical corpus with the embedded QPC Hafs v18 font. U+06DF is omitted from the generated production text because this font does not render it reliably. Sequential tanween is not inserted into stored production text, keeping copying and searching safe.

This is a deliberate source decision; the alternatives considered and the conditions for any future corpus replacement are recorded in docs/QURAN_SOURCE_DECISION.md.

Run npm run quran:import after replacing the source file. The importer validates the 114 surahs and 6,236 ayahs before generating the JSON corpus. Tanzil attribution, display options, and usage terms are available at https://tanzil.net/download/.

---

Demos & Workflows

1. Contextual Verse Extraction & Auto-Detection

Type a search query, select text, or write a chapter/verse mention, then execute Extract Quran verse from context.

2. Snippet Trimming & Toggle View

Crop specific phrases using (word1-word2) shorthand next to a reference, or repeat the extract command to toggle between the snippet and the full verse.

3. Multi-Source Tafsir Retrieval

Fetch commentary for single ayahs or multi-ayah ranges using your preferred books or auto-detected authors mentioned on the line.

4. Ayah Reflection Journaling

Select your reflection text and choose a category to create or append directly to the unified verse note.

Video Walkthrough

▶ Click here to watch the full walkthrough demo

---

Command Reference

Command	Description
Extract Quran verse from context	Primary extraction: resolves queries, ranges, or selections on the current line.
Open global Quran search modal	Opens the full-corpus search modal with live analytics.
Fetch contextual tafsir for current line	Retrieves tafsir commentary for the verse/range at the cursor.
Open global tafsir selection modal	Interactive picker to choose commentary sources first, then select verse range.
Log selection to reflection (choose category)	Interactive modal to pick or create a reflection category for selected text.
Link related ayahs	Multi-select modal to cross-link two or more related verses in frontmatter.
Open or create Quran surah note	Choose a surah and open its complete mushaf-style note; ayah notes are created only when reached.
Log note on Quran ayah	Search for an ayah, optionally choose a range, select a reflection section, and write directly into the notes from one modal.
Convert Quran reference to footnote	Converts inline [Surah:Ayah] to a numbered markdown footnote [^quran1].
Remove Quran reference from line	Strips matched Qur'anic citations from the current line.
Strip tashkeel from selection or line	Removes diacritics/tashkeel from selection or active line.

---

Custom Styling & CSS Reference

You can target plugin elements using Obsidian snippets or via the Custom CSS field in plugin settings:

CSS Selector	Description
.cm-quran-key-text	The Qur'anic verse body inside wrapper glyphs (Editor & Live Preview).
.quran-key-ornate-number	The Arabic-Indic verse number decoration.
.quran-key-ayah-note-link, .quran-key-lazy-ayah	The ayah marker that opens an existing or lazily created ayah note.
.quran-key-highlight	Highlighted matching words inside search modals.
.quran-key-analytics-dashboard	The live analytics stat bar in the search modal.
.quran-key-picker-modal	Modals for tafsir sources, category selection, and ayah linking.

Power-user options, including the optional @ section trigger in the ayah entry modal, are available under Settings → Advanced and are disabled by default.

Styling Examples

/* Add a decorative side border to inserted verses */
.cm-quran-key-text {
    border-right: 3px solid var(--quran-key-color, #dfc56b);
    padding-right: 8px;
}

/* Style ayah numbers with a badge background */
.quran-key-ornate-number {
    background: rgba(223, 197, 107, 0.15);
    padding: 1px 6px;
    border-radius: 4px;
    font-size: 0.9em;
}

---

Network & Privacy Disclosures

In compliance with Obsidian Developer Policies:

• Network Access: This plugin makes outgoing HTTPS requests to tafsir.app (or custom API endpoints configured by the user in Settings) only when a tafsir retrieval command is explicitly executed.
• No Telemetry / Tracking: This plugin does not collect, log, or transmit any analytics, telemetry, or user vault data.
• Offline First: All Qur'an text extraction, local search, normalization, and note-taking features function completely offline without internet connectivity.

---

Installation

From Obsidian Community Plugins

1. Open Settings > Community plugins.
2. Search for Quran Key.
3. Click Install, then Enable.

Manual Installation

1. Download main.js, manifest.json, and styles.css from the latest GitHub Release.
2. Create a folder named quran-key under your vault's .obsidian/plugins/ directory.
3. Copy the downloaded files into .obsidian/plugins/quran-key/.
4. Reload Obsidian and enable Quran Key in Community Plugins settings.

---

License

This project is open source and licensed under the MIT License.