Sefaria Auto Linker

Lev Eliezer Israel edited this page Sep 13, 2018 · 15 revisions

Sefaria Auto-Linker

The Sefaria auto linker recognizes references on a web page, links them to the corresponding texts on Sefaria, and optionally provides a popup containing the text of the references.

It can be run either as a bookmarklet from a browser or embedded into page code. If run as a bookmarklet, a user can find references on any webpage s/he visits by clicking the bookmarklet. If embedded into page code, it will find references every time any user loads the page. (You can get browser bookmarklets here)

Embed Code

Place this code on your web page, just before the </body> tag.

	<script type="text/javascript" charset="utf-8" src=""></script>

You'll want to use on your https pages.


Now and again we may update the linker to provide additional functionality or modify the interface. If you plan on injecting custom styles, you may prefer to use a specific version of the linker. To do so, just simply append the version number to the base file name of the linker. e.g. linker.v2.js. the unversioned linker.js file will always be the most up to date.

Options for embed code

Options can be passed to the call to that will change the behavior of the plugin


The selector option is used to specify which elements should be checked for references. The value of selector is a string - a CSS selector. You can specify an #id a .class or any other CSS selector.

If it is not specified, all of the textual content within the <body> tag is checked for links.


The mode option affects how the found references behave. If not specified, the default is "popup-click" mode.

The value of mode is one of the following strings:

  • "popup-click" - when the the user clicks on a reference, a popup is displayed with the textual content. Within the popup is a link to Sefaria.

  • "link" - The references are turned into links, which open in a new browser tab when clicked. There is no popup with textual content.


The popupStyles option allows for custom styling of the popup box - colors, borders, fonts, etc. If present, it must be a dictionary of JavaScript style attributes and their values. See examples below.

Examples of calling the plugin with options

Only look for references in paragraphs with a "Torah" class.{selector: ".Torah"});

Invoke plugin in click-to-popup mode{mode: "popup-click"});

Add some custom styling to the popup box{
		popupStyles: {
			color: "#e3fc11",
			border: '4em solid black' 

Do all of the above, together{
		mode: "popup-click",
		selector: ".Torah",
		popupStyles: {
			color: "#e3fc11",
                	border: '4em solid black' 

Citation Format

We've worked pretty hard to help the linker capture as many references as possible. In general, if the title is written out in full, followed by the numeric references, it will work well. Every text on Sefaria can be referenced, but some of them are trickier than others.

Going into a bit more detail:

  • Punctuation shouldn't be an issue - space, comma, period, and colon in a reference will all be fine.

  • Dash has special meaning - it indicates a range (see the examples, below.) Any extra dash will trip us up.

  • For each text, we recognize a number of common spelling variants. For example, for "2 Kings", we'll recognize the titles: Melachim Bet, Melachim II, Second Kings, 2 Kings, II Melachim, Kings II, II Melakhim, and II Kings.

  • We'll recognize chapter level and verse level references, as well as ranges, so all of these are valid:

    • Second Kings 2
    • II Kings, 2:5
    • II Kings 2 5
    • Kings II 2-4
    • 2 Kings 2:3-6
    • Melachim II 2:3-3:3
  • Some texts use Talmudic numbering (not just the Talmud), for those, we expect the references in that form. For example:

    • Shabbat 7b
    • Zohar 2, 20b (That means volume 2, page 20b)
    • Rif Shabbat 7b (Refers to 7b in 'dapei ha Rif')

Where we will fail to capture the reference is when the title is interwoven in the text. For example: Mishnah Taanit 4:3 would work well, but In the 3rd Mishnah of Taanit, chapter 4 would fail to match. The general rule is - cite completely, and don't mix anything into the citation. That will work well for most of the core canon - Tanach, Mishnah, Tosefta, Talmud, Midrash, Zohar, etc.

Where it gets trickier is with texts that have a complex structure. For example, to cite the Four Questions in the Haggadah, this citation would work: Haggadah, Magid, Four Questions, as would a number of variants. Still - it's unlikely that a citation like that will occur on its own. The Mishneh Torah is a similar situation - we record many variants of section names of the Mishneh Torah, but citations are hard to get right without looking at exactly how its recorded in our system. A foolproof way of always getting a good reference is to navigate to the text on Sefaria, select the text, and copy the citation from the URL.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.