Qur'an — Multi-Translation Study Website & PDF Typesetting

A static HTML website (GitHub Pages) for side-by-side study of the Qur'an — Arabic text, audio recitation, two transliterations, three English translations, an English explanation, two Hindi translations, and a Hindi Tafsir — plus typeset PDF editions generated with XeLaTeX.

📖 Documentation

Document	Description
DOCUMENTATION_INDEX.md	Start here — master index and navigation guide for all docs
ARCHITECTURE.md	System design, data flow diagrams, component descriptions
API_REFERENCE.md	Python script interfaces, data contracts, format specifications
CODE_WALKTHROUGH.md	File-by-file annotated guide to every source file
DEVELOPER_ONBOARDING.md	Setup instructions and first-contribution walkthrough
DEPLOYMENT_RUNBOOK.md	GitHub Pages deploy, audio server setup, rollback procedures
TROUBLESHOOTING.md	Common errors and fixes for all pipeline stages
GLOSSARY.md	Domain terms, project-specific jargon, acronyms
CHANGELOG_ANALYSIS.md	Project history, milestones, growth metrics
SECURITY_AUDIT_NOTES.md	Vulnerability assessment and security recommendations
PERFORMANCE_BENCHMARKS.md	Build times, data volumes, optimization notes
INTEGRATION_PLAYBOOK.md	Embed data, audio, or the website in other applications
CONTRIBUTION_GUIDE.md	Detailed PR process, coding standards, data standards
FAQ_DEEP_DIVE.md	Comprehensive answers to anticipated questions
APPENDIX_RAW_ANALYSIS.md	Raw metrics, code analysis, edge cases
CONTRIBUTING.md	Quick contributor guide
CHANGELOG.md	Version history

Live Website

https://druvx13.github.io/Quran-data/

Features:

114 Surah pages — every ayah displayed with all content streams
Full-text search (search.html) — searches Arabic, transliteration, Yusuf Ali translation, and Hindi Tafsir; results paginated with match highlighting
Surah navigator — jump to any surah via a dropdown in the page header
Verse & Content Filter — collapsible widget per surah to show specific verse ranges and toggle individual content rows on/off
Audio recitation — per-ayah audio player (Mishary Rashid Alafasy, 128 kbps), streamed from Hugging Face Space

Tech Stack

Component	Technology
PDF typesetting	XeLaTeX with `polyglossia`, `fontspec`, `quran` packages
Script language	Python 3.6+
Web output	Static HTML (GitHub Pages via `docs/`)
Build system	GNU Make
Audio hosting	Hugging Face Space (`druvx13-quran-audio-alafasy.hf.space`)

Repository Structure

.
├── src/                    # Python generator scripts
│   ├── gentexforquran.py   # Generate intermediate LaTeX content files
│   ├── gentxtforquran.py   # Generate formatted plain-text output files
│   └── gendocshtml.py      # Generate static HTML docs (docs/) + lazy search data (docs/sd/)
├── data/                   # All source translation data (input — do not modify)
│   ├── ar.quran.txt                              # Arabic Uthmani script (one line per ayah)
│   ├── en.pickthall.txt                          # English – Pickthall (one line per ayah)
│   ├── en.pickthall.tanzil.txt                   # English – Pickthall – Tanzil.net format (sura|ayah|text)
│   ├── en.sahih.txt                              # English – Saheeh International (one line per ayah)
│   ├── en.sahih.trans.zip                        # English – Saheeh archived zip (reference)
│   ├── en.yusufali.txt                           # English – Yusuf Ali (sura|ayah|text format)
│   ├── en.qarai.txt                              # English – Ali Quli Qarai (sura|ayah|text)
│   ├── en.hilali.txt                             # English – Al-Hilali & Khan (sura|ayah|text)
│   ├── en.ahmedali.txt                           # English – Ahmed Ali (sura|ayah|text)
│   ├── en.ahmedraza.txt                          # English – Ahmed Raza Khan (sura|ayah|text)
│   ├── en.arberry.txt                            # English – A. J. Arberry (sura|ayah|text)
│   ├── en.daryabadi.txt                          # English – Abdul Majid Daryabadi (sura|ayah|text)
│   ├── en.itani.txt                              # English – Talal Itani (sura|ayah|text)
│   ├── en.maududi.txt                            # English – Abul Ala Maududi (sura|ayah|text)
│   ├── en.mubarakpuri.txt                        # English – Safi-ur-Rahman al-Mubarakpuri (sura|ayah|text)
│   ├── en.qaribullah.txt                         # English – Hasan al-Fatih Qaribullah & Ahmad Darwish (sura|ayah|text)
│   ├── en.sarwar.txt                             # English – Muhammad Sarwar (sura|ayah|text)
│   ├── en.shakir.txt                             # English – Mohammad Habib Shakir (sura|ayah|text)
│   ├── en.wahiduddin.txt                         # English – Wahiduddin Khan (sura|ayah|text)
│   ├── en.rwwad.txt                              # English – Rowwad Translation Center (quranenc.com, one line per ayah)
│   ├── en.asad.txt                               # English – Muhammad Asad (alquran.cloud, one line per ayah)
│   ├── en.usmani.txt                             # English – Mufti Taqi Usmani (quran.com, one line per ayah)
│   ├── en.abdelhaleem.txt                        # English – M.A.S. Abdel Haleem (quran.com, one line per ayah)
│   ├── en.transliteration.txt                    # Transliteration – Tanzil.net plain text (one line per ayah)
│   ├── en.transliteration.tanzil.txt             # Transliteration – Tanzil.net with HTML markup (sura|ayah|html-text); used by gendocshtml.py
│   ├── translit_en.txt                           # Transliteration – Quran Unicode Project (num|text)
│   ├── hi.farooq.txt                             # Hindi – Muhammad Farooq Khan & Muhammad Ahmed
│   ├── hi.hindi.txt                              # Hindi – Suhel Farooq Khan & Saifur Rahman Nadwi
│   ├── hi.omari.txt                              # Hindi – Azizul Haq Al-Omari (quranenc.com)
│   ├── abridged-explanation-of-the-quran.json.zip  # English Explanation (JSON, "sura:ayah" keys)
│   ├── hindi-mokhtasar.json.zip                  # Hindi Tafsir – Al-Mokhtasar (JSON, "sura:ayah" keys)
│   ├── rabila-al-umry-simple.json.zip            # Gujarati – Rabila Al-Umry (JSON, "sura:ayah" keys, "t" field)
│   ├── ur.jalandhry.txt                          # Urdu – Fateh Muhammad Jalandhry (sura|ayah|text)
│   ├── ur.ahmedali.txt                           # Urdu – Ahmed Ali (sura|ayah|text)
│   ├── ur.jawadi.txt                             # Urdu – Syed Zeeshan Haider Jawadi (sura|ayah|text)
│   ├── ur.kanzuliman.txt                         # Urdu – Ahmed Raza Khan / Kanz ul Iman (sura|ayah|text)
│   ├── ur.maududi.txt                            # Urdu – Abul Ala Maududi (sura|ayah|text)
│   ├── ur.qadri.txt                              # Urdu – Tahir ul Qadri (sura|ayah|text)
│   ├── ur.junagarhi.txt                          # Urdu – Muhammad Junagarhi (sura|ayah|text)
│   ├── ur.najafi.txt                             # Urdu – Muhammad Husain Najafi (sura|ayah|text)
│   ├── ur.mahmudalhasan.txt                      # Urdu – Shaykh al-Hind Mahmud al-Hasan (quran.com, one line per ayah)
│   ├── ur.zilalquran.txt                         # Urdu – Fe Zilal al-Quran / Sayyid Qutb (quran.com, one line per ayah)
│   ├── ur.bayanulquran.txt                       # Urdu – Bayan-ul-Quran / Dr. Israr Ahmad (quran.com, one line per ayah)
│   ├── ur.wahiduddin.txt                         # Urdu – Maulana Wahiduddin Khan (quran.com, one line per ayah)
│   ├── ur.romanmaududi.txt                       # Roman Urdu – Abul Ala Maududi (quran.com, one line per ayah)
│   ├── ur.romanjunagarhi.txt                     # Roman Urdu – Muhammad Junagarhi (fawazahmed0/quran-api, one line per ayah)
│   ├── ur.karamshah.txt                          # Urdu – Muhammad Karam Shah Al-Azhari (fawazahmed0/quran-api, one line per ayah)
│   ├── ur.taqiusmani.txt                         # Urdu – Muhammad Taqi Usmani (fawazahmed0/quran-api, one line per ayah)
│   ├── en.aishabewley.txt                        # English – Aisha Bewley (fawazahmed0/quran-api, one line per ayah)
│   ├── en.aliunal.txt                            # English – Ali Unal (fawazahmed0/quran-api, one line per ayah)
│   ├── en.lalehbakhtiar.txt                      # English – Dr. Laleh Bakhtiar (fawazahmed0/quran-api, one line per ayah)
│   ├── en.edwardpalmer.txt                       # English – Edward Henry Palmer (fawazahmed0/quran-api, one line per ayah)
│   ├── en.farookmalik.txt                        # English – Farook Malik (fawazahmed0/quran-api, one line per ayah)
│   ├── en.georgesale.txt                         # English – George Sale (fawazahmed0/quran-api, one line per ayah)
│   ├── en.hamidsaziz.txt                         # English – Hamid S. Aziz (fawazahmed0/quran-api, one line per ayah)
│   ├── en.johnrodwell.txt                        # English – John Medows Rodwell (fawazahmed0/quran-api, one line per ayah)
│   ├── en.literal.txt                            # English – Literal / Word for Word (fawazahmed0/quran-api, one line per ayah)
│   ├── en.miraneesuddin.txt                      # English – Mir Aneesuddin (fawazahmed0/quran-api, one line per ayah)
│   ├── en.mohammadshafi.txt                      # English – Mohammad Shafi (fawazahmed0/quran-api, one line per ayah)
│   ├── en.muhammadghali.txt                      # English – Muhammad Mahmoud Ghali (fawazahmed0/quran-api, one line per ayah)
│   ├── en.khattab.txt                            # English – Mustafa Khattab / The Clear Quran (fawazahmed0/quran-api, one line per ayah)
│   ├── en.njdawood.txt                           # English – N. J. Dawood (fawazahmed0/quran-api, one line per ayah)
│   ├── en.safikaskas.txt                         # English – Safi Kaskas (fawazahmed0/quran-api, one line per ayah)
│   ├── en.shabbirahmed.txt                       # English – Shabbir Ahmed (fawazahmed0/quran-api, one line per ayah)
│   ├── en.syedvickar.txt                         # English – Syed Vickar Ahamed (fawazahmed0/quran-api, one line per ayah)
│   ├── en.itaninew.txt                           # English – Talal Itani New Translation (fawazahmed0/quran-api, one line per ayah)
│   ├── en.tbirving.txt                           # English – T. B. Irving (fawazahmed0/quran-api, one line per ayah)
│   ├── en.monotheist.txt                         # English – The Monotheist Group (fawazahmed0/quran-api, one line per ayah)
│   ├── en.ummmuhammad.txt                        # English – Umm Muhammad (fawazahmed0/quran-api, one line per ayah)
│   ├── hi.roman.farooq.txt                       # Romanized Hindi – Muhammad Farooq Khan & Muhammad Ahmed (fawazahmed0/quran-api)
│   ├── hi.roman.suhail.txt                       # Romanized Hindi – Suhel Farooq Khan & Saifur Rahman Nadwi (fawazahmed0/quran-api)
│   ├── hi.roman.omari.txt                        # Romanized Hindi – Maulana Azizul Haque Al-Umari (fawazahmed0/quran-api)
│   ├── gu.roman.rabila.txt                       # Romanized Gujarati – Rabila Al-Omari (fawazahmed0/quran-api)
│   ├── suranamemal.txt                           # Surah names – Malayalam script
│   └── surna.txt                                 # Surah name reference data
├── latex/                  # LaTeX document sources & generated content
│   ├── farooq.tex          # Main document – Farooq Khan Hindi translation
│   ├── suhail.tex          # Main document – Suhel Farooq Khan Hindi translation
│   ├── sahih.tex           # Main document – Saheeh International English
│   ├── translit.tex        # Main document – Tanzil.net transliteration
│   ├── pickthall.tex       # Main document – Pickthall English
│   ├── quran.sty           # Custom LaTeX style (Arabic ayah macros)
│   └── q*.tex              # Generated content files (written by gentexforquran.py)
├── output/                 # Generated output files (written by gentxtforquran.py)
│   ├── quran_arabic.txt
│   ├── quran_english_pickthall.txt
│   ├── quran_english_sahih.txt
│   ├── quran_english_translit.txt
│   ├── quran_english_yusufali.txt
│   ├── quran_english_abridged.txt
│   ├── quran_english_qarai.txt
│   ├── quran_english_hilali.txt
│   ├── quran_english_ahmedali.txt
│   ├── quran_english_ahmedraza.txt
│   ├── quran_english_arberry.txt
│   ├── quran_english_daryabadi.txt
│   ├── quran_english_itani.txt
│   ├── quran_english_maududi.txt
│   ├── quran_english_mubarakpuri.txt
│   ├── quran_english_qaribullah.txt
│   ├── quran_english_sarwar.txt
│   ├── quran_english_shakir.txt
│   ├── quran_english_wahiduddin.txt
│   ├── quran_english_rwwad.txt
│   ├── quran_english_asad.txt
│   ├── quran_english_usmani.txt
│   ├── quran_english_abdelhaleem.txt
│   ├── quran_hindi_farooq.txt
│   ├── quran_hindi_suhail.txt
│   ├── quran_hindi_mokhtasar.txt
│   ├── quran_hindi_omari.txt
│   ├── quran_gujarati_rabila.txt
│   ├── quran_translit_unicode.txt
│   ├── quran_nepali_ahl_al_hadith.txt
│   ├── quran_urdu_jalandhry.txt
│   ├── quran_urdu_ahmedali.txt
│   ├── quran_urdu_jawadi.txt
│   ├── quran_urdu_kanzuliman.txt
│   ├── quran_urdu_maududi.txt
│   ├── quran_urdu_qadri.txt
│   ├── quran_urdu_junagarhi.txt
│   ├── quran_urdu_najafi.txt
│   ├── quran_urdu_mahmudalhasan.txt
│   ├── quran_urdu_zilalquran.txt
│   ├── quran_urdu_bayanulquran.txt
│   ├── quran_urdu_wahiduddin.txt
│   ├── quran_roman_urdu_maududi.txt
│   ├── quran_roman_urdu_junagarhi.txt
│   ├── quran_urdu_karamshah.txt
│   ├── quran_urdu_taqiusmani.txt
│   ├── quran_english_aishabewley.txt
│   ├── quran_english_aliunal.txt
│   ├── quran_english_lalehbakhtiar.txt
│   ├── quran_english_edwardpalmer.txt
│   ├── quran_english_farookmalik.txt
│   ├── quran_english_georgesale.txt
│   ├── quran_english_hamidsaziz.txt
│   ├── quran_english_johnrodwell.txt
│   ├── quran_english_literal.txt
│   ├── quran_english_miraneesuddin.txt
│   ├── quran_english_mohammadshafi.txt
│   ├── quran_english_muhammadghali.txt
│   ├── quran_english_khattab.txt
│   ├── quran_english_njdawood.txt
│   ├── quran_english_safikaskas.txt
│   ├── quran_english_shabbirahmed.txt
│   ├── quran_english_syedvickar.txt
│   ├── quran_english_itaninew.txt
│   ├── quran_english_tbirving.txt
│   ├── quran_english_monotheist.txt
│   ├── quran_english_ummmuhammad.txt
│   ├── quran_roman_hindi_farooq.txt
│   ├── quran_roman_hindi_suhail.txt
│   ├── quran_roman_hindi_omari.txt
│   ├── quran_roman_gujarati_rabila.txt
│   ├── farooq.pdf          # Compiled PDF
│   └── suhail.pdf          # Compiled PDF
├── docs/                   # Generated static HTML – GitHub Pages
│   ├── index.html          # Surah index (last-read card, last bookmark card, surah grid)
│   ├── search.html         # Config-aware full-text search (lazy-loads docs/sd/)
│   ├── bookmarks.html      # Multi-bookmark manager (export/import JSON)
│   ├── config.html         # Settings / preferences
│   ├── sd/                 # Lazy-loaded per-field search data (18 JSON files)
│   └── 001.html … 114.html # Per-surah pages (verse bookmarking, audio, translations)
├── archive/                # Legacy files (Readme.txt, original makefile)
├── Makefile
├── README.md
├── CONTRIBUTING.md
├── CHANGELOG.md
└── LICENSE

Translations & Content

PDF outputs

Output file	Language	Translator
`output/farooq.pdf`	Hindi	Muhammad Farooq Khan & Muhammad Ahmed
`output/suhail.pdf`	Hindi	Suhel Farooq Khan & Saifur Rahman Nadwi
(sahih.pdf — build locally)	English	Saheeh International
(translit.pdf — build locally)	Transliteration	Tanzil.net
(pickthall.pdf — build locally)	English	Pickthall (1930, Public Domain)

HTML website content per ayah

Row	Content	Source
Arabic	Arabic text (Uthmani script)	tanzil.net
Audio	Recitation player	Mishary Rashid Alafasy (128 kbps) — HF Space
Transliteration	Tanzil.net	`data/en.transliteration.tanzil.txt` (HTML-tagged)
Transliteration	Quran Unicode Project	`data/translit_en.txt`
English	Pickthall (1930, Public Domain)	`data/en.pickthall.txt`
English	Yusuf Ali (Public Domain)	`data/en.yusufali.txt`
English	Saheeh International	`data/en.sahih.txt`
English	Ali Quli Qarai	`data/en.qarai.txt`
English	Al-Hilali & Khan	`data/en.hilali.txt`
English	Ahmed Ali	`data/en.ahmedali.txt`
English	Ahmed Raza Khan	`data/en.ahmedraza.txt`
English	A. J. Arberry	`data/en.arberry.txt`
English	Abdul Majid Daryabadi	`data/en.daryabadi.txt`
English	Talal Itani	`data/en.itani.txt`
English	Abul Ala Maududi	`data/en.maududi.txt`
English	Safi-ur-Rahman al-Mubarakpuri	`data/en.mubarakpuri.txt`
English	Hasan al-Fatih Qaribullah & Ahmad Darwish	`data/en.qaribullah.txt`
English	Muhammad Sarwar	`data/en.sarwar.txt`
English	Mohammad Habib Shakir	`data/en.shakir.txt`
English	Wahiduddin Khan	`data/en.wahiduddin.txt`
English	Rowwad Translation Center	`data/en.rwwad.txt`
English	Muhammad Asad	`data/en.asad.txt`
English	Mufti Taqi Usmani	`data/en.usmani.txt`
English	M.A.S. Abdel Haleem	`data/en.abdelhaleem.txt`
English Explanation	Abridged Explanation of the Quran	`data/abridged-explanation-of-the-quran.json.zip`
Hindi (हिन्दी)	Muhammad Farooq Khan & Muhammad Ahmed	`data/hi.farooq.txt`
Hindi (हिन्दी)	Suhel Farooq Khan & Saifur Rahman Nadwi	`data/hi.hindi.txt`
Hindi (हिन्दी)	Azizul Haq Al-Omari	`data/hi.omari.txt`
Hindi Tafsir (हिन्दी तफ्सीर)	Al-Mokhtasar Fi Tafsir Al-Quran Al-Karim	`data/hindi-mokhtasar.json.zip`
Gujarati (ગુજરાતી)	Rabila Al-Umry	`data/rabila-al-umry-simple.json.zip`
Urdu (اردو)	Fateh Muhammad Jalandhry	`data/ur.jalandhry.txt`
Urdu (اردو)	Ahmed Ali	`data/ur.ahmedali.txt`
Urdu (اردو)	Syed Zeeshan Haider Jawadi	`data/ur.jawadi.txt`
Urdu (اردو)	Ahmed Raza Khan (Kanz ul Iman)	`data/ur.kanzuliman.txt`
Urdu (اردو)	Abul Ala Maududi	`data/ur.maududi.txt`
Urdu (اردو)	Tahir ul Qadri	`data/ur.qadri.txt`
Urdu (اردو)	Muhammad Junagarhi	`data/ur.junagarhi.txt`
Urdu (اردو)	Muhammad Husain Najafi	`data/ur.najafi.txt`
Urdu (اردو)	Shaykh al-Hind Mahmud al-Hasan	`data/ur.mahmudalhasan.txt`
Urdu (اردو)	Sayyid Ibrahim Qutb (Fe Zilal al-Quran)	`data/ur.zilalquran.txt`
Urdu (اردو)	Dr. Israr Ahmad (Bayan-ul-Quran)	`data/ur.bayanulquran.txt`
Urdu (اردو)	Maulana Wahiduddin Khan	`data/ur.wahiduddin.txt`
Roman Urdu	Abul Ala Maududi	`data/ur.romanmaududi.txt`
Roman Urdu	Muhammad Junagarhi	`data/ur.romanjunagarhi.txt`

Prerequisites

XeLaTeX (for PDF compilation only) — TeX Live or MiKTeX
- Required fonts: Scheherazade / Scheherazade New (Arabic), Lohit Hindi (Devanagari)
- Required packages: polyglossia, fontspec, forloop, hyperref, menukeys, hologo
Python 3.6+
GNU Make (optional, for convenience)

Installation

Ubuntu / Debian

sudo apt-get install texlive-xetex texlive-lang-arabic texlive-lang-other \
     fonts-lohit-deva fonts-smc-rachana python3

macOS

brew install --cask mactex
brew install python3

Usage

1. Generate intermediate LaTeX content files

python3 src/gentexforquran.py

Reads from data/ and writes latex/qum.tex, latex/qup.tex, latex/qus.tex, latex/qut.tex, and latex/qupk.tex.

2. Compile PDFs

# All PDFs via Make (step 1 must be run first):
make all

# Or individually:
cd latex && xelatex farooq.tex    # → output/farooq.pdf
cd latex && xelatex suhail.tex    # → output/suhail.pdf
cd latex && xelatex sahih.tex     # → output/sahih.pdf
cd latex && xelatex translit.tex  # → output/translit.pdf
cd latex && xelatex pickthall.tex # → output/pickthall.pdf

3. Generate formatted plain-text outputs

python3 src/gentxtforquran.py

Produces forty-four files in output/:

Output file	Source
`quran_arabic.txt`	`data/ar.quran.txt`
`quran_english_pickthall.txt`	`data/en.pickthall.txt`
`quran_english_sahih.txt`	`data/en.sahih.txt`
`quran_english_translit.txt`	`data/en.transliteration.txt`
`quran_english_yusufali.txt`	`data/en.yusufali.txt`
`quran_english_abridged.txt`	`data/abridged-explanation-of-the-quran.json.zip`
`quran_english_qarai.txt`	`data/en.qarai.txt`
`quran_english_hilali.txt`	`data/en.hilali.txt`
`quran_english_ahmedali.txt`	`data/en.ahmedali.txt`
`quran_english_ahmedraza.txt`	`data/en.ahmedraza.txt`
`quran_english_arberry.txt`	`data/en.arberry.txt`
`quran_english_daryabadi.txt`	`data/en.daryabadi.txt`
`quran_english_itani.txt`	`data/en.itani.txt`
`quran_english_maududi.txt`	`data/en.maududi.txt`
`quran_english_mubarakpuri.txt`	`data/en.mubarakpuri.txt`
`quran_english_qaribullah.txt`	`data/en.qaribullah.txt`
`quran_english_sarwar.txt`	`data/en.sarwar.txt`
`quran_english_shakir.txt`	`data/en.shakir.txt`
`quran_english_wahiduddin.txt`	`data/en.wahiduddin.txt`
`quran_english_rwwad.txt`	`data/en.rwwad.txt`
`quran_english_asad.txt`	`data/en.asad.txt`
`quran_english_usmani.txt`	`data/en.usmani.txt`
`quran_english_abdelhaleem.txt`	`data/en.abdelhaleem.txt`
`quran_hindi_farooq.txt`	`data/hi.farooq.txt`
`quran_hindi_suhail.txt`	`data/hi.hindi.txt`
`quran_hindi_mokhtasar.txt`	`data/hindi-mokhtasar.json.zip`
`quran_hindi_omari.txt`	`data/hi.omari.txt`
`quran_gujarati_rabila.txt`	`data/rabila-al-umry-simple.json.zip`
`quran_translit_unicode.txt`	`data/translit_en.txt`
`quran_nepali_ahl_al_hadith.txt`	`data/ahl-al-hadith-central-society-of-nepal-simple.json.zip`
`quran_urdu_jalandhry.txt`	`data/ur.jalandhry.txt`
`quran_urdu_ahmedali.txt`	`data/ur.ahmedali.txt`
`quran_urdu_jawadi.txt`	`data/ur.jawadi.txt`
`quran_urdu_kanzuliman.txt`	`data/ur.kanzuliman.txt`
`quran_urdu_maududi.txt`	`data/ur.maududi.txt`
`quran_urdu_qadri.txt`	`data/ur.qadri.txt`
`quran_urdu_junagarhi.txt`	`data/ur.junagarhi.txt`
`quran_urdu_najafi.txt`	`data/ur.najafi.txt`
`quran_urdu_mahmudalhasan.txt`	`data/ur.mahmudalhasan.txt`
`quran_urdu_zilalquran.txt`	`data/ur.zilalquran.txt`
`quran_urdu_bayanulquran.txt`	`data/ur.bayanulquran.txt`
`quran_urdu_wahiduddin.txt`	`data/ur.wahiduddin.txt`
`quran_roman_urdu_maududi.txt`	`data/ur.romanmaududi.txt`
`quran_roman_urdu_junagarhi.txt`	`data/ur.romanjunagarhi.txt`

All output files use the [sura:ayah] text format, grouped by surah.

4. Regenerate the HTML website (GitHub Pages)

# Step 3 must be run first, then:
python3 src/gendocshtml.py

Regenerates all 114 surah pages, docs/index.html, docs/search.html, docs/bookmarks.html, and the docs/sd/ per-field search JSON files.

Audio note: Audio players stream MP3 files from https://druvx13-quran-audio-alafasy.hf.space/<sura><ayah>.mp3.

Make targets

make all           # Compile all PDFs (requires generate-tex first)
make generate-tex  # Run gentexforquran.py
make generate-txt  # Run gentxtforquran.py
make generate-docs # Run gendocshtml.py (requires generate-txt first)
make clean         # Remove LaTeX build artefacts (.aux, .log, .toc, .out, .synctex.gz)

Hosting Your Own Audio Server

The audio players in docs/ stream MP3 files from a Hugging Face Space that acts as a simple open-directory HTTP server. If you want to host the Alafasy recitation yourself (on Hugging Face Spaces, a VPS, or any Docker-capable host), use the following Dockerfile:

# Use a lightweight Python image
FROM python:3.9-slim

# Set the working directory
WORKDIR /app

# Install required tools for downloading and unzipping
RUN apt-get update && \
    apt-get install -y wget unzip && \
    rm -rf /var/lib/apt/lists/*

# Create a folder specifically for the public files
RUN mkdir -p /app/public

# Download the specific zip file
RUN wget -q https://everyayah.com/data/Alafasy_128kbps/000_versebyverse.zip -O /app/000_versebyverse.zip

# Extract the verses into the public folder
RUN unzip -q /app/000_versebyverse.zip -d /app/public/

# Clean up the original zip file to save disk space
RUN rm /app/000_versebyverse.zip

# Hugging Face Spaces expose port 7860 by default
EXPOSE 7860

# Switch working directory to the public folder so the server roots here
WORKDIR /app/public

# Start Python's built-in HTTP server to create the Open Directory
CMD ["python", "-m", "http.server", "7860"]

⚠️ In case this doesn't work

https://everyayah.com/data/Alafasy_128kbps/000_versebyverse.zip

, you may try

https://web.archive.org/web/20260222041205/https://everyayah.com/data/Alafasy_128kbps/000_versebyverse.zip

Deploy this image on Hugging Face Spaces (Docker SDK), a VPS, or any Docker host. Once running, update the audio src URLs in src/gendocshtml.py (look for hf.space in the file) to point at your server, then re-run python3 src/gendocshtml.py.

Data Sources

Data	Source
Arabic text (Uthmani script)	tanzil.net
Hindi translations	zekr.org (Farooq Khan, Suhel Khan)
Hindi translation (Al-Omari)	quranenc.com (Azizul Haq Al-Omari)
Hindi Tafsir (Al-Mokhtasar)	Al-Mokhtasar Fi Tafsir Al-Quran Al-Karim (JSON)
English translations (Pickthall, Yusuf Ali, Sahih, Hilali, Qarai, Ahmed Ali, Ahmed Raza Khan, Arberry, Daryabadi, Itani, Maududi, Mubarakpuri, Qaribullah, Sarwar, Shakir, Wahiduddin)	tanzil.net
English translation (Rowwad Translation Center)	quranenc.com
English translation (Muhammad Asad)	alquran.cloud
English translations (Mufti Taqi Usmani, M.A.S. Abdel Haleem)	quran.com
English Explanation (Abridged)	Abridged Explanation of the Quran (JSON)
Transliteration (Unicode)	Quran Unicode Project
Urdu translations (Jalandhry, Ahmed Ali, Jawadi, Kanz ul Iman, Maududi, Qadri, Junagarhi, Najafi)	tanzil.net
Urdu translations (Mahmud al-Hasan, Fe Zilal al-Quran, Bayan-ul-Quran, Wahiduddin Khan)	quran.com
Roman Urdu translation (Abul Ala Maududi)	quran.com
Roman Urdu translation (Muhammad Junagarhi)	fawazahmed0/quran-api (jsdelivr CDN)
Audio recitation	Mishary Rashid Alafasy, 128 kbps — versebyversequran.com / HF Hub

License

Copyright (C) 2026 Anonymous
This Work is licensed under the Unconditional Liberty Instrument (ULI), Version 1.0.
A copy of the License is included herein or is available at LICENSE.

This project's scripts and configuration are licensed under the Unconditional Liberty Instrument (ULI), Version 1.0.

The translation texts, audio, and explanation data are reproduced verbatim and are subject to their respective original copyrights and licenses. The Pickthall (1930) and Yusuf Ali translations are in the public domain. All other translations and data are used for non-commercial, educational purposes.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Qur'an — Multi-Translation Study Website & PDF Typesetting

📖 Documentation

Live Website

Tech Stack

Repository Structure

Translations & Content

PDF outputs

HTML website content per ayah

Prerequisites

Installation

Ubuntu / Debian

macOS

Usage

1. Generate intermediate LaTeX content files

2. Compile PDFs

3. Generate formatted plain-text outputs

4. Regenerate the HTML website (GitHub Pages)

Make targets

Hosting Your Own Audio Server

Data Sources

License

About

Uh oh!

Releases

Packages

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 161 Commits
archive		archive
data		data
docs		docs
latex		latex
output		output
src		src
.gitignore		.gitignore
API_REFERENCE.md		API_REFERENCE.md
APPENDIX_RAW_ANALYSIS.md		APPENDIX_RAW_ANALYSIS.md
ARCHITECTURE.md		ARCHITECTURE.md
CHANGELOG.md		CHANGELOG.md
CHANGELOG_ANALYSIS.md		CHANGELOG_ANALYSIS.md
CODE_WALKTHROUGH.md		CODE_WALKTHROUGH.md
CONTRIBUTING.md		CONTRIBUTING.md
CONTRIBUTION_GUIDE.md		CONTRIBUTION_GUIDE.md
DEPLOYMENT_RUNBOOK.md		DEPLOYMENT_RUNBOOK.md
DEVELOPER_ONBOARDING.md		DEVELOPER_ONBOARDING.md
DOCUMENTATION_INDEX.md		DOCUMENTATION_INDEX.md
FAQ_DEEP_DIVE.md		FAQ_DEEP_DIVE.md
GLOSSARY.md		GLOSSARY.md
INTEGRATION_PLAYBOOK.md		INTEGRATION_PLAYBOOK.md
LICENSE		LICENSE
Makefile		Makefile
PERFORMANCE_BENCHMARKS.md		PERFORMANCE_BENCHMARKS.md
README.md		README.md
SECURITY_AUDIT_NOTES.md		SECURITY_AUDIT_NOTES.md
TROUBLESHOOTING.md		TROUBLESHOOTING.md
docs.zip		docs.zip

Folders and files

Latest commit

History

Repository files navigation

Qur'an — Multi-Translation Study Website & PDF Typesetting

📖 Documentation

Live Website

Tech Stack

Repository Structure

Translations & Content

PDF outputs

HTML website content per ayah

Prerequisites

Installation

Ubuntu / Debian

macOS

Usage

1. Generate intermediate LaTeX content files

2. Compile PDFs

3. Generate formatted plain-text outputs

4. Regenerate the HTML website (GitHub Pages)

Make targets

Hosting Your Own Audio Server

Data Sources

License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages