Documentation
Task guides, concept pages and one reference page per package, all built on the quran-ws repositories.
Start here
The four ideas behind most Qur'an-app bugs, a map of the eight packages, and a first page.
Build
Task-shaped guides. Each one starts from an empty file and ends with something running.
Display Qur'an textRead by surah and ayah, and render it with the right font and direction.Display a complete Muṣḥaf pageMount a vectorised page and address every ayah on it.Highlight an ayahTurn a reference into a highlight, on text or on a printed page.Make words clickableWord-level hit-testing, and the word number that survives across blocks.Add Tajwīd highlightingProject rule spans onto text you already render, without wrapping the text.Support multiple riwayatLet a user switch reading without breaking counts, caches or bookmarks.Map ayah references between countsTranslate 7:206 from one counting system into another, correctly.Search the textWhy naive Arabic search misses, and what to index instead.Store bookmarks and progressWhat to persist so a bookmark still resolves after a riwayah or data change.Crop an ayah as an imageOne GET for a shareable image of any ayah.Use markers, frames and ornamentsThe decorative asset set, its variants, and the slot contract.Work offlineBundle sizes, what to ship in-app, and what to fetch.Render on iOS, Android, Flutter and React NativeWhat is available per platform, and where the engine replaces SVG. How our data works
Why the data is shaped this way. Measured, not asserted. When a page states a rule, it links to the rule.
How we build
How Quran.ws builds software that handles the Qur'an. Every rule is one sentence, an example, and the check that catches a violation. Anything not marked adopted is a proposal under discussion. Every page exists in Arabic.
NamingOne concept, one name, the same in the model, the table, the foreign key and the API.Qur'an textThe text is transmitted source data, never edited: encoding, tokenisation, display, and the tests that guard them.Versioning and correctionsA dataset is released, never edited: semantic versioning for data, the errata log, and how a reader is told.EngineeringModel the muṣḥaf, not the screen: tables, identifiers, APIs, storage, fonts, audio and search.Repositories and licensingLayout, commits, review, releases, and what a dependant may rely on.Waqf and open licensingThe licences everything is published under, and the attribution asked for and waived.How to contributeWhere a rule, a term, a data fix or a site mistake goes, and what a pull request needs. Reference
One page per package: what it ships, its shape on disk, its API, and its limits. Then the terms, the registries and the licence coverage.
Quran TextVerified text in seven riwayat, with shared word identity.Qiraat Ayah MapAyah-boundary data and reference translation between counting systems.Qiraat Ayah Map — source filesThe two hand-edited files the mappings are derived from, field by field.Qiraat Ayah Map — method and evidenceWhat is claimed, who transmitted it, how well attested it is, and what the project will not do.Quran SVGVectorised muṣḥaf pages with per-ayah coordinates.Quran SVG ElementsSplit pages: addressable words and marks.Quran AssetsMarkers, frames and ornaments, in three variants.Quran EngineNative rendering for split muṣḥafs, where SVG will not perform.Quran TajweedRule spans over an edition, as character positions.QuranTechGuidance for teams building Qur'an software.Quran PNGThe image tool built on Elements.GlossaryThe terms these docs use, drawn from the dictionary.Terminology dictionaryEvery concept with its canonical name, definition, spellings and source.RegistriesThe closed sets: surahs, qiraat, numbering systems, sajdahs, tajwīd rules.LicensingWhich licence covers which package and which directory.PinningWhere each dataset stands on tags, how to pin one, and what a digest proves.Terminology standardHow a name is derived from its Arabic and how a dictionary entry is written — for maintainers.Decision recordEvery contested naming decision, with its reason and evidence — for maintainers. 50 of 50 pages written. Entries without a link are planned and marked as such rather than published as stubs.