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) directly from the cursor line.
• Quranic Root Search: Search by Arabic roots and highlight the matching Quranic word forms. Press Alt+Enter in the global search modal to toggle root search.
• Snippet Trimming & View Toggle: Extract exact snippets 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.
• Tafsir Packages & Caching: Group preferred tafsir books and cache retrieved commentary inside the vault for offline reuse. Cache files are descriptive JSON files such as tafsir-cache-تفسير-ابن-كثير-القرآن-العظيم-ibn-katheer-surah-2-ayah-255.json; each includes a SHA-256 integrity checksum and is refetched if its content no longer matches.
• 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.
• Orphan Ayah Conversion: Review unlinked Quran passages and convert them into links to ayah notes with rollback support.
• 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/.

Root search uses the Quranic Arabic Corpus morphology data, version 0.4, copyright © 2011 Kais Dukes. The original annotation file and its copyright notice are included under data/vendor; the generated root index preserves source and license metadata. See the Quranic Arabic Corpus download page.

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

Extract a selected phrase 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

Custom Styling & CSS Reference

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

Tafsir packages, persistent caching, custom sources, reflection templates, and orphan-ayah conversion options are available in the plugin settings.

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

The plugin source code is licensed under the MIT License. The Quranic Arabic Corpus morphology data used for root search is a separate third-party work, copyright © 2011 Kais Dukes, with its own GNU GPL and terms of use. The unmodified upstream annotation file and its copyright notice are included in data/vendor; the generated root index retains the source and copyright metadata. See the Quranic Arabic Corpus terms.