README file from
GithubQuran 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
- Open Settings > Community plugins.
- Search for Quran Key.
- Click Install, then Enable.
Manual Installation
- Download main.js, manifest.json, and styles.css from the latest GitHub Release.
- Create a folder named quran-key under your vault's .obsidian/plugins/ directory.
- Copy the downloaded files into .obsidian/plugins/quran-key/.
- Reload Obsidian and enable Quran Key in Community Plugins settings.
License
This project is open source and licensed under the MIT License.