docs: add the libmuslim Hijri calendar API section

[rizukirr]

hijri.h had no documentation on the site at all, despite being the larger of the two headers and the one whose API is hardest to use correctly without guidance.

Three pages under the C section, matching the shape the prayer times section already uses. It sits at position 2, after Prayer times API. hijri.h is C only, since neither the Rust nor the Dart binding vendors it.

Overview

Frames the header as three layers and tells the reader to pick the lowest one that answers their question:

Layer	Use when
Tabular	Fast, deterministic, offline, astronomical accuracy not needed
Local predicates	A date from a named criterion at one observer location
Evening parameters	The raw numbers, to apply your own rule

It states plainly that a local predicate is not a national calendar, with the Kemenag 33-of-37 figure as evidence, because that is the mistake this API most invites.

Quick start

Runs all three layers on the same Gregorian date and gets three different answers:

tabular         1448-02-11 AH
MABIMS 2021     1448-02-12 AH
Umm al-Qura     1448-02-13 AH

That is the clearest way to show there is no single Hijri date and no function that returns one. The page then shows the evening parameters, and the per-term margins behind a failing MABIMS 2021 decision, so a reader can see the difference between missing by 1.38 deg and missing by 0.01 deg.

Every code sample was compiled with -Wall -Wextra -Wpedantic and run. The output blocks are its real output, not transcribed.

API reference

Every public type and function. It also records what the header will not do:

• There is no sunrise finder, only sunset, because only sunset matters to a lunar calendar
• The Sun and Moon are deliberately in different reference frames, and unifying them was measured and made things worse
• Umm al-Qura ships the published table rather than recomputing it, because 198 of 198 was proven unreachable from the published rule
• Yallop is validated against 271 observations. Odeh is not, and links libmuslim#47
• The status enum must be checked, since the out-parameter is left untouched on failure
• strict is per term, which is how you implement the MUIS exceed wording

Three things I got wrong and fixed before pushing

Recording these because they were caught by checking against the header rather than by review:

• hijri_moon_topocentric() takes latitude, longitude and elevation as separate doubles with two out-parameters, not a HijriLocation *
• The gap between the Moon centre and upper limb altitudes is about 0.83 deg, not the quarter degree I first wrote. It carries semidiameter, refraction and parallax together, which makes it larger than several thresholds rather than comparable to them
• The solar residual figures are now the exact measured ones, mean 0.0020391, min -0.0024953, max 0.0084042 deg

Verification

npm run build succeeds with onBrokenLinks: 'throw'.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
muslimtify	Ready	Preview	Aug 18, 2026 11:10am