How to handle references in books?

We’re developing “publications” a process to publish full sets of SC translations as “books” in HTML, EPUB, PDF, and paper.

This is a specific question that I am ruminating on, and would appreciate some feedback. @Snowbird @Brahmali @Suvira @Charlotteannun @cdpatton

And others!

We have stacks of references per sutta. On SC, we can enable or disable these according to user preference. These are highly dependent on the user’s location; someone in a canadian University will want to see the PTS editions; a yodi in a Sri Lankan retreat center will want to see the Buddha Jayanthi; while someone in a Thai forest monastery might want to see the Culalongkorn edition.

When we publish books, the user interface is largely static, and the user cannot select what they want to see. But if you see all of them, the text is unreadable. Indeed, the readability is reduced each time you add a reference series.

So what to do?

option a: just leave them out.

Simple, effective. Someone who wants to check cross-references will do so on the website.

option b: select a few useful ones

This is what we’re doing so far: include the SC main references, the BJ, and the PTS. Both too much and too little IMHO.

It looks something like this.

Now, if we don’t want to display them all by default—and I don’t—we can then add a user config in the CSS. Hide all the references by default, then add a CSS knob like this:

    display:  inline;

Users can enable whatever they want. This would work in both standalone HTML and EPUB. Obviously it requires a degree of user tech savviness.

option c: define references per edition

We could add a configuration option to add references per edition. If I’m publishing a book in Sri Lanka, for example, I could add the BJ references. But this would multiply editions unnecessarily, adding a complex process to the build chain.

option d: embrace the madness, include them all

The problem is there are quite a few, and the markup for each is somewhat verbose. For example, in the case above the first three references look like this:

<a class="sc-main ref" id="mn30:4.1" href="#mn30:4.1">MN 30:4.1</a>
<a class="bj ref" id="bj10.480" href="#bj10.480">BJ 10.480</a>
<a class="pts-vp-pli ref" id="pts-vp-pli1.199" href="#pts-vp-pli1.199">PTS-VP-PLI 1.199</a>

In the Majjhima file, there are about 30,000 such references, even though we only have the three types! If we included all references, it’d be maybe 50,000. That means 50,000 DOM nodes on a single page, for the references alone. Google recommends no more than 1,500 DOM nodes in total. So.

option e: include the first reference per paragraph as data attributes

This is an idea I just had, and I’m leaning towards it. The idea here is that we can use the pre-existing paragraph tags, and add the references to them. Select the first instance of each type of reference, and put it there.

<p data-ref='sc-main-mn1:1.11, bj10.2, cck12.1, csp1ed9.1, csp2ed9.1, dr12.1, ms9M_2, msdiv1, ndp9.3, nya1, pts-vp-pli1.1, sya12.1, vri12.1'>So have I heard …

Now, these remain inert, they don’t add to DOM so they don’t affect page loading or performance. But they can be made use of by a user in various ways.

  • For an occasional check you can inspect the source in the browser.
  • if you want to display one set, you can do a regex and make visible references.
  • someone who wants, for example, to make their own book can manipulate these as they like before adding the HTML to Word or whatever.
  • And so on

Or slightly more verbose, each reference could be its own data-attribute, that way they could still be styled in CSS.

Any thoughts?


The *yodis [sic] in the Sri Lankan retreat centre may wish to see a reference to a Jedi canon.


Thank you for tagging me.

I personally almost never use references to another edition. If you want to check what another edition says, it’s possible to navigate across via the internal headings like sutta name etc. I also think that the cross references reduce readability and confuse people unnecessarily .

But just my personal unscientific opinion. I say leave them out completely.


I’d also say leave them out. It’s hard to imagine these days anyone doing sutta study (unless they were training in the swamps of Dagobah) that wouldn’t have access to a computer to check the references online. Besides, I think of all the people who have no idea what those bracketed numbers in the Wisdom Pub editions are.

Better to make the print books something beautiful.

(although if you wanted to leave the code of the SC segments in epubs, that wouldn’t be a horrible thing, just in case someone was going to use that data in some online project. They don’t take up that much space.)


Does the publication format support endnotes? If a book experience is the main aim, then references could be sparse and placed in endnotes (at the beginning of suttas or vaggas, perhaps?). Or placed in the text as page numbers in brackets. I guess it really depends what audience publications are intended to serve.

Are they general readers? Academics? Bilingual practitioners? They have different needs and wants, but sometimes it works to address one audience’s needs with one format and another audience with a different format. A general reader will be happy having not a single reference anywhere. An academic would probably be happy to know where a sutta begins in a canonical edition when they have a question about a particular passage. A bilingual reader would like to see Pali and translation side by side. It’s not really possible to do it all with a static format, so targeting one of these groups is probably best.


The way that my Bhikkhu Bodhi mobi/epubs ‘pop over’ with endnotes is quite nice as you don’t get bumped around the document.

If you had a symbol/marker as the anchor, which represents that there is a reference and are able to set it in a DIV which has a style to absolute-offset to the right/left of the relative to main paragraph (in the margin) then it wouldn’t interfere with general reading. I don’t know if this is possible for ebook format. I’m just thinking in HTML.

Either like this (as a pop over like above- this is what the triangle represents)

Or like this


+1 to footnotes over endnotes and to the general sentiment that such fine-grained references aren’t useful enough to justify their ink.


I say leave it out altogether. When you started this project, Bhante, you said this would be for ordinary readers, not specialists. I understand your translations were done with this in mind. Regular readers want a nice reading experience, not fancy mark-up. Anyone with special interests can go to the website. That’s what it’s for and that’s where they’ll go. So I say! :slightly_smiling_face:


Thanks everybody for their feedback!

What I’ll end up doing is including a minimal reference in the markup, on a per-paragraph basis. So each paragraph will have an invisible reference:

<p data-ref='mn1:1.4.5`>

This has no effect on appearance or anything else, unless we want it to. It someone wants to see references, they can do so with CSS, or inspect it. I’m thinking of adding these references to the page footer in the printed editions, a little like they are in this mockup.


wondering if you’d consider some programming feat where

  1. a dropdown at the top of each page/sutta that allows a user to pick the references they’d like to see

  2. when picked/enabled the marginalia will show the reference for the relevant line of the sutta.

i’ve found in my own research of other texts or even buddhist texts that references in marginalia per line help exceedingly in analysis!


I understand, but for this you have to use the website. Books are a static medium, and files like EPUB and so on don’t offer this kind of functionality either.

The main purpose is to support reading, rather than research, which I assume will happen mainly on the web.

If you haven’t encountered this function before, on a Pali/English text, go to the “views” menu, scroll right, and activate whatever references you want.

You can even share these via URL. Here I have activated the PTS and Khmer references.


Thanks Bhante @sujato for including me! Sorry I’m late to the party.

Yes yes yes to option e!! Dropping all references would be downright unkind to anyone struggling to cross reference sources, which I believe lots of people actually want and need to do. If I may be allowed to stand in for lots of people.

(Good catch on the Yoda reference @Suvira)