Standardize markup for Vinaya references in notes: proposal

Currently we have two ways to mark a reference in footnotes.

  • Standard markdown: square brackets with what is visually seen, then round brackets with the link.
    • Whole sutta: [DN 1](
    • Segment: [DN 1:123](
  • A convenience form, with just the segment or sutta ID followed by empty round brackets.
    • Whole sutta: [dn1]()
    • Segment: [dn1:123]()

Obviously the convenience form is much easier to write. So far, however, we haven’t built the transformations to make that work for the Vinaya texts.

One difference between Vinaya and Sutta is that in Vinaya the references are much longer, due to having to differentiate between different Vinayas. However normally when showing a reference it is not necessary to display the full ID, as it is clear from context. Thus we have to select a standard set of display forms for Vinaya texts.

This will, at present, only apply to Pali Vinaya. For other Vinayas, and everything else, use standard markdown.

These are the abbreviations I am currently using.

  • Bu Pj (etc.)
  • Bi Ss (etc.)
  • Kd
  • Pvr

So what we need is to transform a segment or sutta ID to the appropriate link.

  • [pli-tv-bu-vb-pj1]()[Bu Pj 1](
  • [pli-tv-bu-vb-pj1:3.4.16]()[Bu Pj 1:3.4.16](

The main thing I’m looking for now is @brahmali’s thoughts. Is this kind of notation good for you? Don’t worry too much what form the references are in currently, I can transform them if need be.

Any other form of link can still be supported by standard markdown, all this does is make it more convenient to write the most common forms of links.


It looks fine. I suppose there are a few categories you will not need, such as Bi Sk, Bi As, and of course Bi Ay. But as long as we have a system that gives unique references to every segment in the corpus, it should be good. So I say go for it. Is there anything I need to do?

Also, by far the majority of my references are to the commentaries. Do we do anything with them?


Excellent, sorry about the slow response.


Not right now. When you’re ready, I’ll work with you to standardize the forms of things in the notes. For now, if you want to do things the easiest possible way, you can add references in the form indicated above, i.e. just throw the text or segment ID in the [squarebrackets]() making sure to follow it with blank round brackets (). But I wouldn’t bother about going back and changing old references at this point, I think it’s okay to leave it a bit rough until we’re ready to standardize them for the Publications project.

Normally they’ll just be plain text, so no markup required. SC links only work within the canon.

If you like, however, you can add [standard markdown links]( to the commentary or anything else, just like you do here on Discourse, and they’ll be handled properly. Just remember that links don’t work in print, so if you want to give precise references with links, word the notes so that they make sense in both linked and plain text.

  • Do: As per [Spk 1.2.3](https://linktospk1.2.3).
  • Don’t: As per the [commentary](https://linktospk1.2.3).

I haven’t been doing this, as the current web edition of the commentary has big pages with no internal links, so we can’t link precisely. I feel like it’s pretty easy to just look up the commentary for a particular texts, so until we have a better way of referencing, I just say “in the commentary”. It seems like a lot of work to add links and references, to little gain. :person_shrugging:

1 Like

Just adding this issue now, can you check that these are the correct forms.

"pli-tv-bu-vb-pj": "Bu Pj", 
"pli-tv-bu-vb-ss": "Bu Ss", 
"pli-tv-bu-vb-ay": "Bu Ay", 
"pli-tv-bu-vb-np": "Bu NP", 
"pli-tv-bu-vb-pc": "Bu Pc", 
"pli-tv-bu-vb-pd": "Bu Pd", 
"pli-tv-bu-vb-sk": "Bu Sk", 
"pli-tv-bu-vb-as": "Bu As", 
"pli-tv-bi-vb-pj": "Bi Pj", 
"pli-tv-bi-vb-ss": "Bi Ss", 
"pli-tv-bi-vb-np": "Bi NP", 
"pli-tv-bi-vb-pc": "Bi Pc", 
"pli-tv-bi-vb-pd": "Bi Pd", 
"pli-tv-kd": "Kd", 
"pli-tv-pvr": "Pvr", 
1 Like