# hadith — An easy way to typeset Hadith in LaTeX

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

**Version 1.1.0** (2025-01-15)

**Author:** Nibras Abo Alzahab <nibras.abo.alzahab@gmail.com>

A LaTeX package for typesetting Hadith from the Seven Canonical Books (Sahih al-Bukhari, Sahih Muslim, Sunan Abi Dawud, Jami at-Tirmidhi, Sunan an-Nasa'i, Sunan Ibn Majah, Muwatta Malik) in XeLaTeX/LuaLaTeX documents.

## Overview

The `hadith` package provides macros for typesetting Hadith text (with Arabic diacritics/tashkeel) from the canonical collections of Islamic tradition. It is modeled after the [`quran`](https://ctan.org/pkg/quran) package and follows the same architecture: text data in `.def` files, macros in `.sty`.

## Features

- **On-demand loading**: Chapter files are loaded only when a hadith from that chapter is requested, avoiding TeX memory limits
- **Seven Canonical Books**: 7 collections included (36,390 hadiths total)
- **English translations**: Built-in translations (enable with `showtrans` option)
- **Hadith grades**: Authenticity grades from scholars (enable with `showgrade` option)
- **Case-insensitive**: Collection names work in any case (`bukhari`, `Bukhari`, `BUKHARI`)
- **Arabic text with full diacritics** (tashkeel)

## Requirements

- **XeLaTeX or LuaLaTeX** (not pdfLaTeX — requires Unicode and RTL support)
- `bidi` package (for right-to-left text)
- `polyglossia` package (for Arabic language support)
- Arabic Unicode font (Amiri, Scheherazade, or KFGQPC Uthmanic)
- `xkeyval`, `xparse`, `xstring` packages

## Installation

### Local installation (for testing)

Copy the files from `tex/` to your TeX tree or set `TEXINPUTS`:

```bash
# Linux/macOS
export TEXINPUTS=/path/to/hadith_package/tex:$TEXINPUTS

# Windows PowerShell
$env:TEXINPUTS = "C:\path\to\hadith_package\tex;" + $env:TEXINPUTS
```

### CTAN installation (future)

```bash
tlmgr install hadith    # TeX Live
mpm --install=hadith    # MiKTeX
```

## Usage

### Basic example

```latex
% !TEX program = xelatex
\documentclass[12pt,a4paper]{article}

\usepackage{bidi}
\usepackage[no-math]{fontspec}
\usepackage[quiet]{polyglossia}

\setmainfont[Scale=1]{Amiri-Regular.ttf}
\newfontfamily\arabicfont[Script=Arabic]{Amiri-Regular.ttf}
\setdefaultlanguage[calendar=gregorian]{arabic}
\setotherlanguage[variant=british]{english}

% Load hadith package with all available books, grades, and translations
\usepackage[bukhari,muslim,abudawud,tirmidhi,nasai,ibnmajah,malik,showgrade,showtrans]{hadith}

\usepackage[breaklinks,hidelinks]{hyperref}

\begin{document}

% Typeset hadith #1 from Sahih al-Bukhari (with grade + translation)
\hadith[bukhari][1]

% Case-insensitive collection names
\hadith[Bukhari][8]
\hadith[BUKHARI][7000]

% Shortcut commands
\hadithmuslim{1}

% Citation (inline)
قال النبي ﷺ: \hadithcite[bukhari][1]

% Collection name
\hadithname{bukhari}

\end{document}
```

### Package options

| Option | Description |
| ------ | ----------- |
| `bukhari` | Load Sahih al-Bukhari |
| `muslim` | Load Sahih Muslim |
| `abudawud` | Load Sunan Abi Dawud |
| `tirmidhi` | Load Jami at-Tirmidhi |
| `nasai` | Load Sunan an-Nasa'i |
| `ibnmajah` | Load Sunan Ibn Majah |
| `malik` | Load Muwatta Malik |
| `ahmad` | Load Musnad Ahmad (not yet available) |
| `darimi` | Load Sunan al-Darimi (not yet available) |
| `sixbooks` | Load the Six Canonical Books (default) |
| `all` | Load all 7 available collections |
| `nonumber` | Hide hadith numbers |
| `ornbraces` | Use ornamental brackets ﴿ ﴾ for numbers |
| `compact` | Compact formatting |
| `showgrade` | Show hadith grades (default: on) |
| `showtrans` | Show English translations (default: off) |

### Commands

| Command | Description |
| ------- | ----------- |
| `\hadith[collection][number]` | Typeset a specific hadith |
| `\hadith*[collection][number]` | Typeset with paragraph break |
| `\hadithrange[collection][start-end]` | Typeset a range of hadiths |
| `\hadithbukhari{number}` | Shortcut for `\hadith[bukhari][number]` |
| `\hadithmuslim{number}` | Shortcut for `\hadith[muslim][number]` |
| `\hadithabudawud{number}` | Shortcut for `\hadith[abudawud][number]` |
| `\hadithtirmidhi{number}` | Shortcut for `\hadith[tirmidhi][number]` |
| `\hadithnasai{number}` | Shortcut for `\hadith[nasai][number]` |
| `\hadithibnmajah{number}` | Shortcut for `\hadith[ibnmajah][number]` |
| `\hadithmalik{number}` | Shortcut for `\hadith[malik][number]` |
| `\hadithcite[collection][number]` | Inline citation |
| `\hadithname{collection}` | Get collection display name |
| `\hadithsection{collection}{number}` | Get section/chapter name |

### Collection names

Collection names are **case-insensitive**: `bukhari`, `Bukhari`, `BUKHARI` all work.

Available collections: `bukhari`, `muslim`, `abudawud`, `tirmidhi`, `nasai`, `ibnmajah`, `malik`.

## Data Source

Hadith text is sourced from [fawazahmed0/hadith-api](https://github.com/fawazahmed0/hadith-api) (public domain / The Unlicense).

- Arabic text with full diacritics (tashkeel)
- 7 canonical collections
- 36,390 hadiths total
- English translations included

### Collection sizes

| Collection | Hadiths | Chapters |
| ---------- | ------- | -------- |
| Sahih al-Bukhari | 7,589 | 98 |
| Sahih Muslim | 7,563 | 57 |
| Sunan Abi Dawud | 5,274 | 43 |
| Jami at-Tirmidhi | 3,998 | 49 |
| Sunan an-Nasa'i | 5,765 | 52 |
| Sunan Ibn Majah | 4,343 | 38 |
| Muwatta Malik | 1,858 | 62 |
| ---------- | ------- | -------- |
| **Total** | **36,390** | **399** |

> **Note:** The traditional "Nine Books" (الكتب التسعة) also include Musnad Ahmad and Sunan al-Darimi, but these are not available in the data source (fawazahmed0/hadith-api). The package code includes options for `ahmad` and `darimi` for future expansion when data becomes available.

## On-Demand Loading

The package uses on-demand loading to avoid TeX memory limits. Only the metadata (index) files are loaded at package initialization. Chapter text files are loaded automatically when a hadith from that chapter is first requested. This keeps memory usage low even with 36,390 hadiths across 7 collections.

## Building from source

### Prerequisites

- Python 3.x
- XeLaTeX

### Generate .def files from JSON

```bash
python source/tools/generate_def.py data/ara-bukhari.json tex/bukhari bukhari --trans data/eng-bukhari.json
```

### Test compilation

```bash
xelatex test_hadith.tex
```

## License

- **Package code** (`.sty`, documentation): LPPL 1.3c
- **Hadith text data** (`.def` files): Public domain (source: The Unlicense)
- **Hadith text itself**: Classical works, centuries old, public domain