Created/edited by GitHub Copilot; pending human review.

Text tools reference

This page lists the names exported by @sefaria/text-transform and the HTML that normalizeText produces. normalizeText makes Sefaria's HTML safe to display. Run it before applyVocalizationToHtml, which doesn't sanitize. createTextPreview accepts raw HTML and normalizes it itself.

Which release this describes

This page documents the code on the main branch. The source stamp is not an npm release or a development snapshot. This copy was built from commit 6fde603.

Install an exact npm version or use a version-pinned npm CDN module. The npm alpha tag moves between reviewed prereleases. It is not a main-build snapshot. Older pinned releases keep their own behavior and can lack APIs added since. Install and status lists package commands and jsDelivr/UNPKG files.

Functions and types

Import all of these from the package root.

Functions

applyVocalization()

function applyVocalization(text, mode, options?): string;

Applies a vocalization preset to plain text without Unicode normalization.

Parameters

Parameter	Type
text	string
mode	VocalizationMode
options	VocalizationOptions

Returns

string

Throws

When a runtime mode or PASEQ value is unsupported.

---

applyVocalizationToHtml()

function applyVocalizationToHtml(html, mode, options?): string;

Applies vocalization only to text nodes in an already-sanitized HTML fragment.

Run normalizeText first. Markup and attribute values are preserved. This operation is not a sanitizer.

Parameters

Parameter	Type
html	string
mode	VocalizationMode
options	VocalizationOptions

Returns

string

Throws

When a runtime mode or PASEQ value is unsupported.

---

createTextPreview()

function createTextPreview(input, maximumGraphemes?): TextPreview;

Accepts raw HTML, normalizes it, and bounds rendered graphemes across inline node boundaries. Footnotes, annotations, and link interaction are omitted from this compact view.

Parameters

Parameter	Type	Default value
input	string	—
maximumGraphemes	number	3500

Returns

TextPreview

---

normalizeText()

function normalizeText(html, options?): NormalizedText;

Converts untrusted Sefaria text markup into safe, directly renderable HTML.

The operation parses once, removes unsupported attributes, emits no URLs, and extracts footnotes into result-local records. Options can narrow but never widen the fixed output grammar.

Parameters

Parameter	Type
html	string
options	NormalizeTextOptions

Returns

NormalizedText

Remarks

Output keeps only these ordinary inline tags without attributes: b, strong, i, em, u, small, sup, and sub. It keeps br, maps big to <span style="font-size: larger;">, converts img to its alt text, unwraps block elements with separators, and removes active content. Incoming style attributes are dropped. The fixed font-size: larger; style emitted for big is the only output style. The only ordinary attribute is dir, and only on i or generated span elements when the value is ltr, rtl, or auto.

Recognized structural attributes are data-sefaria-note, data-sefaria-end-footnote, data-sefaria-commentary-marker, data-sefaria-commentator, data-sefaria-label, data-sefaria-order, data-sefaria-overlay, data-sefaria-value, data-sefaria-ref, data-sefaria-ven, data-sefaria-vhe, data-sefaria-slug, and data-sefaria-mam. Footnote placeholders use data-sefaria-note values that match note keys in NormalizedText.notes.

Example

normalizeText(
  'See <a data-ref="Micah 6:8" href="/Micah.6.8">Micah</a><script>x()</script>',
).bodyHtml;
// 'See <span data-sefaria-ref="Micah 6:8">Micah</span>'

Throws

When commentary reference input is invalid.

Throws

When projected output exceeds max(65_536, html.length * 8) UTF-16 code units.

Interfaces

CommentaryReference

One source-scoped commentary target supplied by a validated host boundary.

Properties

Property	Modifier	Type	Description
commentator	readonly	string	Exact source commentator name.
label?	readonly	string	Exact source label, when present.
order?	readonly	string | number	Exact source order, when present.
ref	readonly	string	Sefaria reference supplied by matching link evidence.

---

NormalizedFootnote

One normalized footnote referenced by a local body placeholder.

Properties

Property	Modifier	Type	Description
contentHtml	readonly	string | null	Independently safe, balanced body HTML, empty when present-empty, or null when missing.
key	readonly	number	Zero-based key local to one normalization result and used as the matching data-sefaria-note value.
markerHtml	readonly	string	Independently safe, balanced marker HTML.

---

NormalizedText

Safe, deterministic HTML plus source-ordered footnotes.

Properties

Property	Modifier	Type	Description
bodyHtml	readonly	string	Complete safe body HTML with empty data-sefaria-note placeholders whose values are note keys.
notes	readonly	readonly NormalizedFootnote[]	Source-ordered notes referenced by body or note-content placeholders.

---

NormalizeTextOptions

Feature-narrowing inputs for normalizeText.

Properties

Property	Modifier	Type	Description
allowFootnotes?	readonly	boolean	Retain recognized footnotes. Defaults to true. When enabled, footnote markers keep data-sefaria-note placeholders whose values are result-local note keys. End-of-text markers also keep data-sefaria-end-footnote when allowInlineAnnotations is enabled.
allowInlineAnnotations?	readonly	boolean	Retain commentary, overlay, and standalone annotation metadata. Defaults to true. When enabled, end-of-text footnote markers keep data-sefaria-end-footnote when allowFootnotes is also enabled, commentary markers keep data-sefaria-commentary-marker, commentary anchors keep data-sefaria-commentator, data-sefaria-label, and data-sefaria-order; matching commentary references can add data-sefaria-ref. Overlay anchors keep data-sefaria-overlay plus data-sefaria-value. When disabled, those attributes and their empty anchor elements are dropped.
allowNamedEntities?	readonly	boolean	Retain named-entity identity as data-sefaria-slug. Defaults to true. When disabled, named-entity links are unwrapped and only their text remains.
allowRefLinks?	readonly	boolean	Retain explicit Sefaria reference identity. Defaults to true. When enabled, reference links keep data-sefaria-ref and optional data-sefaria-ven, data-sefaria-vhe, and approved dir. When disabled, reference links are unwrapped and those attributes are dropped.
commentaryReferences?	readonly	readonly CommentaryReference[]	Optional exact commentary targets prepared from source-scoped link evidence. Matching entries add data-sefaria-ref to commentary anchors that are also retained by allowInlineAnnotations. The value is dropped when there is no exact, unique match.

---

TextPreview

Sanitized, bounded text with an explicit truncation indicator.

Properties

Property	Modifier	Type	Description
html	readonly	string	Balanced safe HTML for rendering.
text	readonly	string	Decoded text, including newline separators, for accessibility and counting.
truncated	readonly	boolean	Whether visible input remains beyond the requested bound.

---

VocalizationOptions

Optional behavior for vocalization transforms.

Properties

Property	Type	Description
paseq?	PaseqMode	Selects whether every PASEQ or only whitespace-prefixed PASEQ is removed.

Type Aliases

PaseqMode

type PaseqMode = "always" | "after-space";

Policy used for U+05C0 PASEQ when cantillation is removed.

---

VocalizationMode

type VocalizationMode = "taamim_and_nikkud" | "nikkud" | "none";

Supported Hebrew vocalization-preservation presets.

Normalized HTML output

normalizeText returns bodyHtml and footnote HTML with no links, no event handlers and no scripts. It emits only the attributes listed in this section, plus approved dir values and the fixed style value generated for <big>. Addresses can still appear as ordinary text or inside an attribute value, such as a reference. This section is generated from normalize.ts, and each example below is the function's real output.

Elements

• These formatting elements are kept, with no attributes except dir on <i>: <b>, <strong>, <i>, <em>, <u>, <small>, <sup>, <sub>.
• <br> is kept with no attributes.
• <big> becomes <span style="font-size: larger;">. This is the only style attribute in the output. Incoming styles are removed.
• <img> is replaced by its alt text.
• Toolkit-specific markup is output as <span> elements with the attributes below.
• Block elements, such as <blockquote>, are unwrapped with a separator kept between their contents.
• Scripts, styles and similar active content are removed. Other elements are unwrapped, keeping their text.
• dir is kept only when its value is ltr, rtl or auto.

Attributes

The last column names the NormalizeTextOptions setting that controls the markup. The four allow… settings default to true. commentaryReferences defaults to none, so a commentary anchor gets data-sefaria-ref only when you supply a matching reference. Masorah markings are kept when a <span> has exactly one recognized Masorah class.

Attribute	Element	Meaning	Controlled by
data-sefaria-note	<span>	An empty placeholder where a footnote was. Its value is the note's key in notes.	allowFootnotes
data-sefaria-end-footnote	<span>	An end-of-text footnote marker. The value is the marker's text; the element is empty.	allowFootnotes and allowInlineAnnotations
data-sefaria-commentary-marker	<span>	A commentary marker. The value is the marker's text; the element is empty.	allowInlineAnnotations
data-sefaria-commentator	<span>	A commentary anchor. The value is the commentator's name. The element is empty.	allowInlineAnnotations
data-sefaria-label	<span>	The commentary anchor's label, copied from the source when present.	allowInlineAnnotations
data-sefaria-order	<span>	The commentary anchor's order, copied from the source when present.	allowInlineAnnotations
data-sefaria-overlay	<span>	An overlay anchor's name, such as a reading division. It always appears with data-sefaria-value. The element is empty.	allowInlineAnnotations
data-sefaria-value	<span>	The overlay anchor's value.	allowInlineAnnotations
data-sefaria-ref	<span>	A Sefaria reference. On a former reference link, it holds the link's reference and the link text is kept. On a commentary anchor, it holds the reference that commentaryReferences supplied for that commentator, order and label.	allowRefLinks; on commentary anchors, allowInlineAnnotations and commentaryReferences
data-sefaria-ven	<span>	The English version title from a reference link, when present.	allowRefLinks
data-sefaria-vhe	<span>	The Hebrew version title from a reference link, when present.	allowRefLinks
data-sefaria-slug	<span>	A named entity's topic slug. The entity's text is kept.	allowNamedEntities
data-sefaria-mam	<span>	A Miqra according to the Masorah marking. The value is one of the names in the table below.	none

Masorah markings

data-sefaria-mam takes one of these values, converted from Sefaria's class names:

Sefaria class	data-sefaria-mam value
mam-spi-pe	petuchah
mam-spi-samekh	setumah
mam-spi-invnun	inverted-nun
mam-kq	ketiv-qere
mam-kq-k	ketiv
mam-kq-q	qere
mam-kq-trivial	trivial-variant

Examples

<!-- Input -->
He has told you<sup class="footnote-marker">1</sup
><i class="footnote">A note.</i>
<!-- Output -->
He has told you<span data-sefaria-note="0"></span>

<!-- Input -->
Text<sup class="endFootnote">*</sup>
<!-- Output -->
Text<span data-sefaria-end-footnote="*"></span>

<!-- Input -->
Text<sup class="itag">a</sup>
<!-- Output -->
Text<span data-sefaria-commentary-marker="a"></span>

<!-- Input -->
Text<i data-commentator="Rashi" data-order="1" data-label="a"></i>
<!-- Output -->
Text<span
  data-sefaria-commentator="Rashi"
  data-sefaria-label="a"
  data-sefaria-order="1"
></span>

<!-- Input -->
Text<i data-overlay="Weekday Torah Reading" data-value="Monday"></i>
<!-- Output -->
Text<span
  data-sefaria-overlay="Weekday Torah Reading"
  data-sefaria-value="Monday"
></span>

<!-- Input -->
See <a class="refLink" href="/Micah.6.8" data-ref="Micah 6:8">Micah 6:8</a>
<!-- Output -->
See <span data-sefaria-ref="Micah 6:8">Micah 6:8</span>

<!-- Input -->
See <a data-ref="Micah 6:8" data-ven="The Contemporary Torah">Micah 6:8</a>
<!-- Output -->
See
<span data-sefaria-ref="Micah 6:8" data-sefaria-ven="The Contemporary Torah"
  >Micah 6:8</span
>

<!-- Input -->
See
<a data-ref="Micah 6:8" data-vhe="Miqra according to the Masorah">Micah 6:8</a>
<!-- Output -->
See
<span
  data-sefaria-ref="Micah 6:8"
  data-sefaria-vhe="Miqra according to the Masorah"
  >Micah 6:8</span
>

<!-- Input -->
<a class="namedEntityLink" data-slug="micah" href="/topics/micah">Micah</a>
<!-- Output -->
<span data-sefaria-slug="micah">Micah</span>

<!-- Input -->
<span class="mam-spi-pe">{פ}</span>
<!-- Output -->
<span data-sefaria-mam="petuchah">{פ}</span>

Where to go next

• Clean up stored Sefaria text shows these functions in use.
• Clean text and safety explains why normalizing comes first.