Search the main text or the footnotes of a Shamela book

How do you tell whether a sentence in a Shamela search result is the author’s main text or an editor’s footnote? Read the matchedIn field on each hit, search one layer with search_in, or read the page and compare its body and foot fields. The rest of this page shows each of the three on the live server.

A page in a printed classical book has two voices. The main text (matn) is the author’s. The footnotes (hawashi) are usually an editor’s: sources, variant readings, and quotations from other scholars. A search that cannot tell them apart will attribute an editor’s note to the author.

Maktabah al-Shamela stores them in separate fields, and the Quran Gallery server at https://qurangallery.com/mcp/shamela keeps them separate in every result.

Three ways a client can tell

1. matchedIn on every curated hit. shamela_search_library says body, footnote, both or unknown for each passage.
2. search_in on the raw search tools. shamela_search can be limited to body or foot, and its hits report matched_in.
3. The page itself. shamela_read (unit: 'page') returns body, foot and comment as separate fields, so a client can compare the two layers of one page.

See which voice a hit came from

Every passage from shamela_search_library has a matchedIn field: body (the main text), footnote, both (the words occur in each), or unknown (the layer could not be determined). The raw shamela_* search tools report the same thing as matched_in, a list that can hold body, foot or both.

A real example. This request searches the eight primary hadith collections for «إنما الأعمال بالنيات»:

{
	"name": "shamela_search_library",
	"arguments": { "query": "إنما الأعمال بالنيات", "scope": "hadith-primary" }
}

On 2026-11-01 it returned five passages, listed here by book:

The two al-Nasa’i passages carry the words in the main text and in a footnote (both), and match as separate words, not as the exact phrase (all_terms): the main text there reads «إنَّما الأعمالُ بالنِّيَّة», in the singular. The Abu Dawud passage is the one a careless reader gets wrong. On that page the main text reads «إنما الأعمال بالنية», in the singular. The exact wording the search matched is in the editor’s footnote, which quotes al-Khattabi: «قال الخطابي: قوله: إنما الأعمال بالنيات…». Abu Dawud’s own words are not what matched.

Search only one voice

Two modes of shamela_search take the filter as an ordinary top-level argument, search_in: match: 'phrase' and match: 'boolean'. Its values are body and foot, and the default is both.

Body only:

{
	"name": "shamela_search",
	"arguments": {
		"match": "phrase",
		"query": "إنما الأعمال بالنيات",
		"scope": { "book_ids": [117359, 98138, 1681] },
		"search_in": ["body"]
	}
}

This returns two verified hits, Sunan Ibn Majah 5/ 305 and Sahih al-Bukhari 1/ 6, both with matched_in: ["body"].

Footnotes only, same query and books:

{
	"name": "shamela_search",
	"arguments": {
		"match": "phrase",
		"query": "إنما الأعمال بالنيات",
		"scope": { "book_ids": [117359, 98138, 1681] },
		"search_in": ["foot"]
	}
}

This returns one hit, Sunan Abi Dawud 3/ 526, with matched_in: ["foot"].

shamela_search (match: 'words') takes the same filter inside an options object:

{
	"name": "shamela_search",
	"arguments": {
		"query": "الوقف",
		"scope": { "category_ids": [6] },
		"options": { "search_in": ["body"] }
	}
}

Where search_in goes depends on the tool, and the tool’s schema is the authority. A misplaced argument is rejected, not ignored: sending options to shamela_search (match: 'phrase') fails with “BAD_ARG: options is not used when match=‘phrase’; it applies to match=‘words’.“.

What the filter does not reach

The page also has a third field, comment, that holds readers’ notes. It is not searchable: search_in accepts only body and foot, and comment is rejected as an invalid value (“Expected ‘body’ | ‘foot’, received ‘comment’”).

shamela_find (kind: 'heading'), shamela_find (kind: 'book') and shamela_find (kind: 'author') also accept options.search_in, but it changes nothing, because they search chapter headings and catalogue entries, not page text. In a test, «باب الصيام» returned the same 634 headings for ["body"], ["foot"] and both. Search page text with shamela_search (match: 'words') or shamela_search (match: 'phrase').

Combine terms across a layer

shamela_search (match: 'boolean') takes all_of, any_of and none_of terms, evaluated as one query over the whole index, so total_hits is exact. With search_in set, each sub-search looks only in the layer you named. It also lists zero_hit_terms, the words that occur nowhere in the index, which is how you tell a misspelled term from a genuinely rare one.

Read both layers of one page

shamela_read (unit: 'page') returns the page as separate fields: body, foot and comment. For Sahih al-Bukhari page id 10 (printed 1/ 6), body holds the hadith with its chain and foot is empty. For Abu Dawud page id 1796 (printed 3/ 526), both are filled (checked 2026-11-01: body 414 characters, foot 1,069). The footnote and comment come with the first part of the body when a long page is split into parts of about 4,000 characters.

Citing only printed pages

Not every book’s page numbers match a printing. scope.citable_only: true keeps only the books Shamela marks as matching a printed edition. In the current library that is 7,177 of 8,594 entries; the other 1,417 are paginated by Shamela itself, and a page number from them is not a reference to any published edition. Set it whenever the answer will quote a page as a citation.

A search that combines the two filters, restricted to category 6:

{
	"name": "shamela_search",
	"arguments": {
		"query": "الوقف",
		"scope": { "category_ids": [6], "citable_only": true },
		"options": { "search_in": ["body"] }
	}
}

This kind of query reports its own scale: scope_count is the number of books it ranged over and total_hits the number of pages that match.

What the curated tools do

shamela_search_library, search and fetch take no layer filter. They return both voices and mark which is which: shamela_search_library gives every passage a matchedIn, search appends ”[footnote match]” to the title of a footnote hit, and fetch returns the page with its footnotes under a separate label. The default job is “find where this is printed, and tell me which voice said it”. Use the raw tools above when you need to exclude one voice, for example when you are looking for an author’s definition and want to ignore every editor’s quotation of it.

See Reading a result for the full field list and Verify a quotation for checking a citation against the page.