Skip to content

Adding items to the library

Jump to bottom
The Open Buddhist University edited this page Apr 4, 2023 · 18 revisions

This guide will help walk you through how to add a new item to the library.

Category

The first thing you'll have to determine is whether the item has already 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! 🙈

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 in the form: work-title_author.md Where:

  • The work-title slug 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 to the end 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)
  • The entire filename must not contain spaces, apostrophes, quotes, uppercase letters or unicode characters.

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: 
---

>

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?"

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)

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

authors:
  - bodhi
  - sujato
  - "Someone Else"
  - "Another Author and others"

If the work is a sutta, for example, you may erase this field and 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. Canonical (i.e. from the original publisher) links are preferred if possible.

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

source_url

The canonical url may be undesirable if it's a redirect url (such as a DOI), a confusing webpage, a poor 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 will be status: featured. For most works, simply erase this line.

For more information about how this works, see the collection policy document.

Course and Tags

The course field gets the slug of the _tag or _course that this piece of content belongs to, and the tags list is for all the topics this item is related to.

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.

OLID

This is an OpenLibrary ID.

We use the OpenLibrary API for monograph covers. If you're adding a new monograph 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 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 IFF the item is an article.

Journal can be a slug (journal: jjrs) or a string (journal: "Good Housekeeping"). See _journals for the list of available journal slugs.

Publisher and Address

The company or organization which published a work.

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

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

If a string publisher is specified, you should also provide an "address" which is simply the city or country where a work was published, e.g. address: "New York"

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.

Book

papers and excerpts must have either booktitle OR from_book set.

from_book takes a 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 Markdown.

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 or dilemma.

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 sometimes be omitted and the number of pull quotes can sometimes vary as well.

Below these paragraphs is the place to add links to additional information, related works, etc.

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

Finishing Up

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

Any questions not answered here? Feel free to email me

Clone this wiki locally