Nilakkhana (markdown) and inline HTML in bilara data - suttacentral/bilara-data GitHub Wiki

We aim to minimize or eliminate inline markup in bilara-data segments.

Note: never use block-level markup (paragraphs, lists, headings, blockquotes, etc.) in sutta translations or comments!

Markdown makes the work of the translator easier. It is some simple plain-text marks that are converted automatically to HTML. You’ve probably used Markdown—for example, on our Discourse forum—but if you’re not familiar with it, check this explainer.

Bilara follows a slightly customized implementation of markdown, which we call Nilakkhana (Which means "markdown" in Pali!). The basic ideas are simple.

• _underscore_ for quoting foreign words (esp. Pali) (= <i>).
• *asterisks* to emphasize words (= <em>).
• **double asterisks** for things that stand out, like headwords in definitions. You probably don't want to use this (= <b>).

To make a link in Markdown, enclose the visible text in [square brackets], then the link in (round brackets). We offer a simplified syntax for internal links (cross-references).

• Standard markdown for external links: [Dog](https://en.m.wikipedia.org/wiki/Dog).
• For internal links, use the simplified form to link to segment or sutta
  • [an9.14:11.11]() becomes <a href='/an9.14/en/sujato#11.11>AN 9.14:11.11</a>.
  • [an9.14]() becomes <a href='/an9.14/en/sujato>AN 9.14</a>.

Always use the exact segment number or sutta UID, nothing else! Note that a sutta UID is all lowercase and has no spaces.

Normally this should be enough. But in some cases it may be convenient to display different text for the link.

For example, the UIDs for Vinaya texts are long and unwieldy. In such cases, specify the exact display form in the square brackets. This will not be altered in any way.

• [Pj 1:5.1.11](pli-tv-bu-vb-pj1:5.1.110) becomes <a href='/pli-tv-bu-vb-pj1/en/brahmali#5.1.11>Pj 1:5.1.11</a>

You can use the same approach to indicate a range of text.

• [AN 9.14:11.1–6](an9.14:11.1) (of course, you will use en-dash for ranges!)

Or a section of a larger text.

• [DN 1:2](dn1:2.1.1)

In each of these cases, the URL (in round brackets) must be a valid segment number or sutta UID.

As a general rule: don’t try to be clever. Do the simplest and most obvious thing.

Markdown does not cover all our uses. The following remain as HTML.

• custom tags, especially for text-critical markup
• <cite>
• <span class='subject'> and similar
  • could use custom tag instead: <subject>
• It is possible to add block-level markup to site essays, but only if you know what you’re doing, and in any case it is always better to avoid this unless absolutely necessary.