Note:

This documentation covers the latest version of the Sefaria Auto Linker (version 3) which is currently not the default version. Linker v3 currently only offers advantages for Hebrew content. The results should be about equivalent when run on English content. The new version decreases incorrect links and catches many more types of citations. For documentation for the default version (version 2) see Linker v2.

Bookmarklet

We don't currently have a Javascript bookmarklet available for Linker v3 although you can easily adapt the bookmarklet linked at the bottom of this page by following this documentation.

Embed Code

Place this code on your web page, just before the </body> tag. These lines will work for a static HTML page. If your site dynamically loads content after the page loads (e.g. Single Page Applications) see the note at the bottom for dynamic sites.

	<script type="text/javascript" charset="utf-8" src="https://www.sefaria.org/linker.v3.js"></script>
	<script>
	    sefaria.link();
	</script>

Options

Options can be passed to sefaria.link() as key-value pairs in an object. (See examples below)

`mode`

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.

`contentLang`

Sets the language used to display the textual content in the popup. Options are bilingual, english, and hebrew. The default value is bilingual.

`interfaceLang`

Sets the language of the popup interface which controls the text in the bottom bar as well as the orientation from left to right or right to left. Options are english or hebrew. The default value is english.

`excludeFromLinking`

Sets a CSS selector that defines elements on the page that you do not want to be linked. This may be useful for example if you have page headers where having links or a popup could be distracting. Anything within an existing <a> tag will be excluded by default. Citations that are found but excluded are still tracked for usage in the Web Pages section on Sefaria. The value of the parameter is a string which is any valid CSS selector.

`whitelistSelector`

Sets a CSS selector that defines elements on the page that should always be searched for citations. This field shouldn't be necessary to fill in by default since the linker relies on heuristics to find the main page content. However, this parameter can be used in cases where part of the page is missed

`dynamic`

Set to true if you are calling the linker dynamically when content on your page changes after the initial page load. The tracking signal that the linker sends back to Sefaria so that pages can be included in our sidebar sends will normally look first canonical link tag on your page to set its URL. Since most dynamic sites don't update this tag as they change, setting dynamic to true will cause the linker to look to window.href for the URL instead.

`popupStyles`

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.

`hidePopupsOnMobile`

By default, for a better user experience, on small screens the Linker won't attempt to create popups, and instead will fall back to the link mode. If you want to use popups on all screen sizes, set this parameter to false.

`versionPreferencesByCorpus`

By default, the popup window will display the default version for each text. Use this parameter to specify preferred versions. If the version title doesn't exist for that text, the default version will be used. You can find version titles available for each book by visiting the books table of contents and clicking the "Versions" tab. E.g. here are the versions for Genesis. Each version preference needs to be organized by language and corpus in the following format:

{
   <other linker options>,
   "versionPreferencesByCorpus": {
      <corpus>: {
         <lang>: <version title>
      }
   }
}

corpus can take one of the following values: Tanakh, Bavli, Yerushalmi, Mishnah, Midrash Rabbah. Below is an example usage:

{
   "versionPreferencesByCorpus": {
      "Tanakh": {
         "en": "The Koren Jerusalem Bible"
      },
      "Bavli": {
         "he": "Wikisource Talmud Bavli"
      }
   }
}

In this example, "The Koren Jerusalem Bible" version will be used for English for all Tanakh texts. The "Wikisource Talmud Bavli" version will be used for Hebrew for all Bavli texts. In the case either version doesn't exist, the default will be used.

`debug`

If true, will turn on debug mode which may help to determine why a certain citation isn't being linked. In debug mode, citations will be surrounded by a colored border with the following meanings

green border: citation successfully linked
red border: citation recognized but not successfully linked. Either Sefaria doesn't have this text, the citation was incorrectly marked or the linker has a bug. Note, these citations will not appear when debug mode is false.
yellow border: citation was linked to multiple possible links because it was determined to be ambiguous. Note, ambiguous citations will not appear when debug mode is off.

To report an issue with a citation in debug mode, click the citation you want to report and click "Report" (this button only appears in debug mode).

Deprecated options

As of version 3 of the linker, the following options are no longer supported:

selector
excludeFromTracking
parenthesesOnly
quotationOnly

Dynamic Sites

The linker code searches for citations and creates links once when sefaria.link() is called. If you have a dynamic site where content changes after page load, you can make additional calls to sefaria.link() any time your content changes. You should pass the parameter {dynamic: true} to ensure the linker can recognize the correct URL for the page if it has changed.

Versions

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.v3.js. the unversioned linker.js file will always be the most up to date.

Examples

Include elements with "Torah" class in search for citations.

	sefaria.link({whitelistSelector: ".Torah"});

Invoke plugin in click-to-popup mode

	sefaria.link({mode: "popup-click"});

Add some custom styling to the popup box

	sefaria.link({
		popupStyles: {
			color: "#e3fc11",
			border: '4em solid black' 
		}
	});

Do all of the above, together

	sefaria.link({
		mode: "popup-click",
		whitelistSelector: ".Torah",
		popupStyles: {
			color: "#e3fc11",
                	border: '4em solid black' 
		}
	});

Use only Hebrew for the interface and content

	sefaria.link({
		contentLang: "hebrew",
		interfaceLang: "hebrew"
	});

Citation Format

As of version 3, the linker should be able to recognize most types of citations. Below are a few examples of the types of citations which should work:

בראשית א
רשי ראש השנה ד״ה אלא ביבנה
פרק מאימתי
פרק בתרא דפסחים
שם פרק ג
בראשית פרק א עד פרק ד

Note, the linker supports ibid / שם citations although in practice it is cautious to link these since these currently cause many false positives.

Use the debug option defined above above to investigate why a citation wasn't linked