Skip to content

Adding items to the library

Jump to bottom
The Open Buddhist University edited this page May 1, 2023 · 18 revisions

Introduction

After a work is accepted for inclusion in the Drive Library, it will need to be coded up for addition to the website.

This is done by adding a new markdown file to the _content/ folder in our repository. This guide will walk you through how to write one of those files.

Category

The first thing you'll have to determine is whether the item has been added to the library already! Try searching for it first to make sure it has yet to be added before continuing on.

Once you've confirmed that it needs to be added, you'll then have to consider what kind of item is it?

The library has nine content categories, which are the subfolders of the main _content folder:

  1. articles
  2. av
  3. booklets
  4. canon
  5. essays
  6. excerpts
  7. monographs
  8. papers
  9. reference

These break down as follows:

  • Audio/Visual material goes into "av".
  • Canonical works (e.g. suttas) go into "canon".
  • Self-published books are "booklets"
  • Books with professional publishers are "monographs"
  • Self-published writings shorter than a book are called "essays"
  • unless they were published as part of a book, in which case it's an "excerpt".
  • If a research paper was published in a journal or periodical, that's an "article"
  • If it was published in an edited volume, that's a "paper".
  • "Reference" is basically anything else.

Simple! 🙈

String Types

There are two kinds of strings in our files: slugs and literals.

Slugs are all lowercase and don't contain spaces or special characters. They are used as filenames and as IDs for different files to refer to one another. For example, course: tranquility-and-insight in a piece will link that work to the /courses/tranquility-and-insight course. By convention, we don't put slugs in quotes to show that they aren't literal strings but are rather references to other "database" objects.

Literal strings, by contrast, are wrapped in " quote marks and will be displayed or used exactly as written. For example, editor: "Anna Wintour" will display her name exactly like that in the work's bibliographic information.

Note: Numbers are also never put in quotes. For example, minutes: 5

The Filename

Once you've decided which subfolder your new item belongs in, your new entry will need a name. The filename is important as Jekyll will use the name to generate the URL for the item.

Library item filenames should be a slug in the form: work-title_author.md. The entire filename must not contain spaces, apostrophes, quotes, uppercase letters or unicode characters. It must be entirely lowercase with hyphens and contain at most one underscore.

  • The work-title portion should usually not start with a- or the-
  • The author's names should come after an underscore, in last(-first) format
  • Works with two authors should just list their last names last1-last2
  • -et-al can be added for works with many authors
  • authors with entries in the _authors folder should use that slug instead of their full name (e.g. just some-title_appleton.md instead of some-title_appleton-naomi.md)
  • It must end in .md to show Jekyll that it is a markdown file.

The template

Whenever I make a new entry, I first paste this template as the body of the new file:

---
title: ""
authors:
  - 
subcat: 
editor: ""
translator: 
external_url: ""
source_url: ""
drive_links:
  - ""
file_links:
  - ""
formats: []
status: featured
course: 
tags:
  - 
year: 
month: 
olid: 
oclc: 
journal: 
publisher: 
address: ""
volume: 
series: 
number: 
from_book: 
booktitle: ""
pages: "--"
chapter: 
minutes: 
---

> pull quote

Description

Don't worry! You won't need to fill in most of these. Having a template just means that you won't accidentally forget or mistype a field.

Let's go through this template one line at a time to understand it.

Frontmatter ---

The first line contains exactly three hyphens.

This tells Jekyll that what follows is Yaml-formatted frontmatter data.

See this guide for more information about Yaml syntax.

Title

The title of the work. This field is required for all items in the library.

If a word in the title needs to be italicized, add an asterisk before and after it:

title: "The Meaning of *sati*: Memory or Mindfulness?"

If a title contains a double quote, escape it with a slash:

title: "What is the \"Best\" Meditation Technique?"

(OR use Unicode “fancy” quotes, which don't need to be escaped)

Authors

This is a yaml list of author objects.

An author object is either:

  1. A quoted string containing the full name of the author (e.g. "Mark Twain")
  2. The slug of an _author/ (e.g. bodhi for Bhikkhu Bodhi)

To check if an author already has an entry, check the authors list on the site. Their name will link to e.g. https://buddhistuniversity.net/authors/bodhi: the last part of that URL will be the author's slug.

If there are more than five authors, you can add and others to the end of the fourth author, for example:

authors:
  - bodhi
  - sujato
  - "S. B. Else"
  - "Another Author and others"

Initials in names should end in a dot and a space (e.g. "P. F. Chang") and non-slugified names should use capital letters UNLESS the author explicitly prefers otherwise (e.g. "ee cummings" or "bell hooks").

If the work is a sutta, for example, you may erase this field entirely and just fill in translator: instead (see below).

Subcat

This field can be one of the following values: thesis, poetry, podcast, music, film, course, or fiction.

If none of those is applicable, this field may be erased.

Editor and Translator

These fields each take one author object as above.

If there are multiple editors, put them into one long string separated by " and ". For example, editor: "Bugs Bunny and Daffy Duck and Porky Pig"

external_url

This is the main link to the item.

The link must be to the actual item itself and not to e.g. a review. It should link to the best version, even if that's not the e.g. publisher's.

If a url points directly to a PDF file (which is encouraged!), the link must begin with https:// as Chrome no longer supports downloading PDFs from insecure URLs.

Note that links to Google Drive don't go here. They have a dedicated field below.

source_url

The canonical url (e.g. from the original publisher or author) may be undesirable if it's a redirect (such as a DOI), a confusing webpage, a low-quality PDF, grouped together with other content, served only over http, etc.

In such cases, the canonical url (or similar) may be put here in "source_url" and a better url should be placed in external_url if one is available.

These URLs will be checked monthly to ensure that they are still live and will be updated as needed.

Drive Links

This field is a list of Google Drive links to the item in question.

Usually there will only be one link (to a PDF), but the list allows for multiple links if the work is available in multiple formats (see below).

File Links

If the file is hosted directly by OBU, its file handles will appear here.

Formats

This array tells the formats of the Drive and file links above. By default, this is formats: [mp3] for av works and formats: [pdf, epub] for everything else.

Erase this template line if you're okay with the defaults.

Status

Works of especially high quality which you thoroughly enjoyed and enthusiastically recommend should get status: featured. For most works, however, you will simply erase this line.

For more information about what this flag does and how to determine when to use it, see the collection policy document.

Course and Tags

The course: field gets the slug of the _tag or _course that this piece of content primarily belongs to (i.e. the folder it's in in Google Drive).

The tags: list contains the _tags (or slugified keywords) that this work is also related to.

For example, an article about monks in Thailand helping the poor might get course: engaged to mark it as primarily about "Engaged Buddhism" and tags: [thai] to show that it's also about "Thai Buddhism."

Tags should primarily be _tag slugs from the tag ontology.

A work should not usually be tagged with both a tag and that tag's immediate parent or sibling. For example, a work about thai Buddhism is obviously also about theravada and a work about philosophy is clearly also about right view. Just one of these tags will suffice. Similarly, wanting to tag a work with siblings (e.g. chan and tantric) is a good sign to consider a broader tag instead (in this case, perhaps mahayana-roots?).

You may add tags that aren't slugs if the work is specifically about something not currently in the ontology (e.g. avijja). Such keywords are still helpful for search and may help identify topics for future addition.

Year and Month

When the work was first published, approximately.

The year (e.g. year: 2013) is required for all items. If it's unknown, make an educated guess and add a comment explaining what you know, for example:

year: 1999 # sometime 1995–2003

Month is the first three letters of the month name in lower case, e.g. month: sep if known. This field is not required.

OLID

This is an OpenLibrary ID.

We use the OpenLibrary API for monograph covers. If you're adding a new book and want it to have a pretty picture of the cover, find (or add) the book on OpenLibrary and upload a snazzy cover image for it there. Then simply copy and paste the OLID to this field and the cover will magically appear on the site. 🪄

OCLC

This is the WorldCat identifier, added for copyrighted monographs.

Journal

The periodical that an article was published in.

This field is used if and only if the item is an article.

Journal can be a _journals slug (journal: jjrs) or a string (journal: "Good Housekeeping").

See the full list of journals on the site to check if a journal has a full entry already or not. These links will have the journal slug at the end.

Publisher and Address

The company or organization which published a work.

Required for monographs, it must be absent from booklets and is optional for all other categories.

Publisher can be a slug (bps) or a string ("Acme Corp"). See the _publishers folder or the list of publishers on the site for the list of possible slugs.

If a publisher is specified, you may also want to provide an "address" which is simply the city or country where a work was published, e.g. address: "New York" This field is optional and may be omitted if unknown.

Volume

If you know the volume number for the journal issue, supply it here.

Series

This is a slug to a _series object, used to tie N, numbered items together.

First, create a _series/ file for the series as a whole, then add all the items in that series, setting series: my-new-series

Number

This is either the number in the series or the number in the volume.

This field is required if series is present, optional otherwise.

Book

papers and excerpts must have either booktitle OR from_book set.

from_book takes a _content/monograph/ slug and booktitle takes a simple string.

Pages

Either a page count or a page range.

If this is a journal article or book excerpt, specify the page range in the format pages: "5--24".

For other written works, specify the number of ~A4-sized pages it would take to print the work. For example, a 100-page, A5-sized booklet should have pages: 50

This field is required for all works other than reference, av and canon.

Chapter

The chapter number for an excerpt or paper if known.

Minutes

The duration of an Audio/Video recording.

This field must be a whole number of minutes and is required for all av items.

Frontmatter end ---

This line tells Jekyll that the Yaml data is over and we're ready to start supplying the page's main Markdown content.

The Markdown description

The typical item in the library starts with a catchy pull quote from the work and then has a description of the work, in the form:

> It was the best of times,
> it was the worst of times...

A book about some specific topic
recommended for people interested in
some particular question.

Crafting this prose is more art than science, but know that the first paragraph will get featured independently on the tag pages. If the pull quote is e.g. from the abstract and summarizes the work well, the prose description may be omitted and you can include multiple pull quotes as well if so inclined.

Below these paragraphs is the place to add miscellaneous notes, such as links to additional information, related works, critical responses, necessary context, etc.

This markdown is processed into HTML by Kramdown so for formatting questions, see their documentation.

A Shortcut

If the item you're adding is an academic article, there's a good chance it's in the OpenAlex Database. To search for it there and automatically draft a preliminary OBU entry from their data, run:

python3 scripts/openaleximporter.py

But note that this is just a draft and will require you to fill in any missing or incorrect information.

Finishing Up

Once you're satisfied with your new addition(s), put up a Pull Request and Khemarato Bhikkhu will review it!

Any questions not answered here? Feel free to email me

Clone this wiki locally