Quran and Hadith Fetcher

بِسْمِ اللَّهِ الرَّحْمَٰنِ الرَّحِيمِ

Quran and Hadith Fetcher is an Obsidian plugin that fetches Quran Ayaat and also Ahadith from multiple online sources. It also has some additional features useful for the seeker of Islamic knowledge like: previewing the Quran/Hadith before inserting, optional offline databases, and other useful text formatting options.

It supports multiple languages, translations, and Ahadith books (depending on the provider).

Disclaimer: Please double check. Do not trust this plugin or the hadith providers for scholarly work.

Usage

Run these commands in the command palette (Ctrl-p)

Command	Description
Fetch Quran	Get Quranic Ayaat. Supports ranges like 10-15.
Fetch Hadith	Get Ahadith. Also supports ranges.

Fetching is limited to 30 Ayaat and 15 Ahadith to prevent accidental fetches and resource usage. These can easily be modified in the settings.

Command: Fetch Quran

• Select a Surah: Choose from a conveniently sorted list.
• Fetch Specific Ayat: Input a single Ayah (e.g., 10) or a custom range (e.g., 10-15).
• Customize Content: Toggle Arabic text, English translation, embedded links, and footnotes.
• Adjust Layout: Format the final output to display merged into a paragraph or separated line-by-line.

Tip: Use root words to get your Surah/Hadith Book more easily, like frq to get 025 Al-Furqaan

Command: Fetch Ahadith

• Select a Hadith Book: Choose from a list of Ahadith books (according to the provider set in settings).
• Fetch Specific Ayat: Input a single or multiple Ahadith (e.g., 5 or 5-10)
• Customize Content: Toggle Arabic text, English translation, embedded links, and Grading.

Preview Window

After choosing output options for both the above commands, the plugin opens an editable preview. Here you can either modify the text to your liking before inserting it in current note or copying it.

Other Commands

These commands can be enabled from the settings

Command	Description
Set Hadith content provider	Select the default API or database provider used to fetch Hadith data.
Set Quran translation	Choose the preferred Quran translator or translation edition (e.g., Sahih International).
Set Quran content provider	Choose the source API or data engine used for retrieving Quranic text.
Normalize all salutations to ﷺ	Convert all Prophet honorifics/salutations in the selection to the Arabic symbol ﷺ.
Convert Variants of RA used for the Sahaba to رَضِيَ ٱللَّٰهُ عَنْهُ	Standardize text variations of "RA" for Companions into Arabic (رَضِيَ ٱللَّٰهُ عَنْهُ). Also works on "May Allah be pleased with him/her/them"
Check provider health	Verify server status and network connectivity for active content providers.
Toggle Text Conversions	Quickly enable or disable automatic text conversions
Manage offline databases	Open the database management modal used for downloading and removing databases for offline use.
Set Quran link website	Configure the website used when embedding website link in fetched Ayaat
Set Hadith translation	Set the default translation for Hadith text.
Set Quran translation language	Select the primary language for Quran translations.

Settings and commands

Settings include provider and translation selection, Quran link destination, formatting, text conversions, range limits, cache control, provider health checks, offline database management, and command-palette visibility.

The two fetch commands and provider health check are enabled by default, along with salutation normalization. Other provider-selection, offline-management, and conversion commands are available in the command palette and can be enabled or disabled in Command palette commands.

Providers

Quran and Hadith providers are selected independently in Settings → Provider Settings for Quran & Hadith. Available translations and collections depend on the selected provider.

Network use: Fetching a passage sends its selected Quran/Hadith reference and translation choice to the selected provider. Loading catalogs and installing offline databases also requests that provider's service or published data files; health checks contact each configured provider. These requests retrieve passage content, metadata, or offline data. The plugin does not send the note body.

Type	Provider	Available data
Quran	Al Quran Cloud	Arabic Quran text and translations discovered from its edition catalog.
Quran	Quran Unlocked	Arabic text and English translations listed by the provider adapter.
Quran	Quran API	Arabic text and translations discovered from its edition catalog.
Quran	Quran Project API	Arabic text and English, Bengali, and Urdu translations.
Hadith	hadith-api	Collections and translations from its edition catalog, with Arabic and translation editions retrieved separately.
Hadith	Hadith Unlocked	Its supported collection catalog and English translation.
Hadith	Hadith JSON	17 books from the pinned hadith-json v1.2.0 dataset, with Arabic and English text. Uses Sunnah.com data (e.g., using 202a for Sahih Muslim)

Providers may differ in the collections, translations, grading, source links, and offline data they expose. The plugin does not guarantee that every number exists in every provider's version of a collection; the provider response is authoritative for an individual Hadith number.

New installs use Al Quran Cloud and hadith-api. English is the default translation language; Hilali-Khan is preferred for Quran where available. Fetch options start with Arabic, English, and links enabled; Hadith grading is enabled by default. Output uses an Obsidian Quote callout unless changed in formatting settings.

Recommended providers: Quran Unlocked and Al-Quran Cloud for Quran, and Hadith Unlocked then Hadith-API for Hadith

Offline databases and caching

Open Settings → Offline databases → Manage or run Manage offline databases from the command palette to install or remove available datasets. Offline databases are stored in the vault's Obsidian plugin data directory. The available downloads are:

• Quran API: a complete Arabic edition and separate downloadable translation editions.
• Quran Project API: the complete Quran with Arabic plus English, Bengali, and Urdu translations, downloaded as 114 Surah files.
• Hadith Unlocked: a complete JSON database for each supported collection.
• hadith-api: paired Arabic and English editions for collections that provide both.
• Hadith JSON: a complete book JSON file for each of its 17 supported books.

Where a provider has a relevant installed database, it checks local data before its runtime cache or network source. Offline coverage depends on which datasets and translations you install. The plugin validates downloaded parts as JSON and installs a database as a unit; cancelled or failed replacement keeps the prior installed copy.

Most provider result caches are bounded, in-memory caches and can be disabled in settings. Hadith JSON is book-oriented: its first online lookup for a book downloads the complete book, then keeps a bounded set in memory and a persistent copy on disk when caching is enabled. Installing that book as an offline database avoids the online download.

Output and text conversions

Each fetch lets you choose Arabic text, English text, links, and Hadith grading where available. Bukhari and Muslim also show a grading toggle for the default “Sahih” grade used when a provider supplies no grade, so you can hide or include that fallback. Quran ranges can be displayed line by line, merged, alternating Arabic and English, or as numbered lines; Quran footnotes can also be included (Quran Unlocked only). Hadith output can separate the chain of narration (Isnad) from the text (Hadith Unlocked only). Formatting settings control callouts, prefixes/suffixes, text surroundings, ayah-number styles, and code-syntax handling.

Text conversions run on fetched text before formatting. Settings can normalize common ﷺ salutations, convert variants of the Sahaba honorific, simplify selected transliteration marks, and apply enabled English replacement rules in their configured order. The Quran Arabic text path only applies the Arabic salutation normalization; English replacement rules are not applied to Arabic text. Conversions can be disabled with the master Toggle Text Conversions setting or command.

The Normalize all salutations to ﷺ and Convert Variants of RA… commands operate on the current editor selection, or on the current line when there is no selection. They do not process the entire note automatically.

Quran links use a selectable destination (Quran Unlocked, Quran.com, QuranWBW, or a custom template). Custom templates accept $surah, $ayah, and $ayahlast; $surah is required. Hadith links use the selected provider's source URL.

Multiple spaces are converted into a single space automatically

Hadith-JSON has \n in its texts, this is also automatically replaced by a single space.

Warning: Text conversions may behave unexpectedly. You can always toggle them OFF in the settings.

Development

Requirements: Node.js 20 or newer and npm.

npm ci
npm run check
npm test
npm run build

npm run build creates the Obsidian plugin bundle, main.js. Unit tests use TypeScript compilation and Node's built-in test runner; they do not require live provider requests. npm run release:prepare runs the checks and build, verifies release metadata, and copies main.js, manifest.json, and styles.css into the ignored release/ directory.

Project layout

src/
  core/       Formatting, transformations, URLs, caching, HTTP, and shared helpers
  domain/     Provider-independent models and interfaces
  parsing/    Reference parsing and validation
  providers/  Quran and Hadith provider adapters and parsers
  obsidian/   Obsidian UI, settings, and Vault storage adapters
  settings/   Defaults and persisted-settings migration
  tests/      Network-free unit tests
scripts/      Release metadata check and release packaging

The plugin uses Obsidian's APIs for HTTP and vault storage.

Known Bugs

• HadithUnlocked Offline databases do not work properly

License

MIT LICENSE