Furqan

Furqan is an Obsidian plugin for reading, studying, reflecting on, and organizing your Quran journey inside your personal knowledge vault.

It combines a Quran reader, Mushaf-style reading, tafsir access, bookmarks, reflections, reading progress, generated Quran notes, and Obsidian's linking/graph features into one local-first study workflow.

Furqan is currently in development. Until it is reviewed and published as an Obsidian Community Plugin, you can install it manually as a development plugin.

---

Why Furqan?

Many people reconnect strongly with the Quran during Ramadan, but struggle to keep that connection consistent afterwards. Reading progress, saved ayat, reflections, memorization notes, and tafsir study often end up scattered across different apps or notebooks.

Furqan brings these pieces together inside Obsidian so your Quran study can become part of your long-term personal knowledge system.

The goal is not to replace the Mushaf or scholarly study. Furqan is a companion tool that helps you read, review, reflect, organize, and return to the Quran with more consistency.

---

Features

Quran journey dashboard

A dedicated dashboard for your Quran routine:

• Daily page goal
• Current reading progress
• Reading streak
• Reflection count
• Activity grid
• Quick actions for continuing reading, opening the Mushaf, searching, and syncing progress

Mushaf view

A focused Mushaf-style reading experience:

• Navigate Quran pages
• Jump to a specific page
• Mark pages as read
• Open related study views from ayah interactions

Verse-by-verse Quran reader

A study-focused Quran reader:

• Arabic text
• Translation
• Tafsir panel
• Mark ayah as read
• Bookmark ayah
• Copy Arabic text or reference
• Insert ayah as a quote into the active note
• Create reflection notes from ayat

Bookmarks and reflections library

A central place to review saved ayat and reflection notes:

• View bookmarked ayat
• Open related Surah, Mushaf page, or tafsir
• Open reflection notes directly from the library

Generated Quran vault

Furqan can generate structured Quran notes inside your vault:

• Surah notes
• Page notes
• Quran index
• Reading progress checkboxes
• Memorization/review checkboxes
• Metadata and tags for organization

Because these are real Obsidian notes, you can use Obsidian features such as:

• Backlinks
• Tags
• Search
• Graph view
• Templates
• Highlights
• Custom dashboards
• Personal study notes

Custom reading collections

Create focused Quran study collections based on ayah ranges you want to read, review, or memorize together.

Examples:

• A story passage
• A memorization plan
• A Friday reading plan
• A personal review set
• A themed study list

---

Commands

After enabling the plugin, open the Obsidian command palette and search for Furqan/Quran commands.

Available commands include:

• Open journey dashboard
• Open bookmarks and reflections
• Open reader
• Open Surah list
• Open Mushaf
• Search
• Generate vault (604 pages + 114 surahs)
• Create custom reading collection

The plugin also adds ribbon icons for quick access to the journey dashboard, library, and Mushaf view.

---

Manual development installation

Until Furqan is available in Obsidian's Community Plugins directory, you can install it manually.

Requirements

• Obsidian desktop app
• Node.js 18 or newer recommended
• npm
• Git

1. Locate your Obsidian vault

Find the vault where you want to test Furqan.

Inside that vault, go to:

<YourVault>/.obsidian/plugins/

If the plugins folder does not exist, create it.

2. Clone the repository

Clone this project into your vault's plugin folder.

Example:

<YourVault>/.obsidian/plugins/furqan/

The final path should look like this:

<YourVault>/.obsidian/plugins/furqan/manifest.json

3. Install dependencies

From the plugin folder, run:

npm install

4. Build the plugin

For a production build, run:

npm run build

This creates the bundled main.js file that Obsidian loads.

For development with automatic rebuilds, run:

npm run dev

5. Enable the plugin in Obsidian

Open Obsidian and go to:

Settings → Community plugins

Then:

1. Turn off Restricted mode if needed.
2. Select Reload plugins if the plugin does not appear.
3. Enable Furqan.

You should now see Furqan commands in the command palette and ribbon icons in the sidebar.

---

Recommended first steps

After enabling Furqan:

1. Open the command palette.
2. Run Open journey dashboard.
3. Open Mushaf and mark a page as read.
4. Open Reader and try tafsir, bookmarks, and reflection actions.
5. Run Generate vault (604 pages + 114 surahs) if you want Quran notes inside your vault.
6. Use Obsidian tags, links, and graph view to organize your study progress.

---

Settings

Furqan includes settings for:

• Default translation
• Default tafsir
• Arabic font size
• Showing or hiding Arabic text
• Showing or hiding translation
• Daily page goal
• Sync toggle
• Mushaf identifier
• Interface language

---

Privacy and data

Furqan is designed around a local-first Obsidian workflow.

Generated notes, bookmarks, reflections, and reading progress are stored in your Obsidian vault/plugin data. Some features use Quran Foundation/Quran.com APIs to retrieve Quran content such as verses, translations, tafsir, and related data.

If sync features are enabled, relevant reading or user activity data may be sent to the configured Quran Foundation user API service. Sync can be disabled from plugin settings.

Do not publish private vault content, personal plugin data, API secrets, or access tokens when sharing your development copy.

---

Development

Useful npm scripts:

• npm run dev — build in development/watch mode
• npm run build — type-check and create a production bundle
• npm run lint — run linting

Main source files live in src/.

Important files:

• src/main.ts — plugin lifecycle, commands, and view registration
• src/views/ — Obsidian views such as dashboard, reader, Mushaf, search, and library
• src/generators/ — Quran vault generation
• src/modals/ — custom collection modal
• src/services/ — journey/progress services
• src/utils/ — API helpers and utilities
• styles.css — plugin styling
• manifest.json — Obsidian plugin manifest

---

Build artifacts

For local testing, Obsidian needs these files at the plugin root:

• manifest.json
• main.js
• styles.css

Do not commit node_modules/ or private vault data.

---

Status

Furqan is currently a development/hackathon project and may still have bugs or incomplete features.

The plan is to submit it for Obsidian Community Plugin review, insha'Allah. Until then, manual installation is the recommended way to test it.

---

License

This project is released under the license included in the repository. See LICENSE for details.