Adding items to the library

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

Category

The first thing you'll have to decide is 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 is published in a journal or periodical, that's an "article"
• If it was a published in an edited volume, it's a "paper".
• "Reference" is basically anything else.

The Filename

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

Library item filenames should be in the form: work-title_work-author.md Where:

• The work title slug should usually not start with a- or the-
• The author's names should come after the only underscore, in alphabetical format
• Works with two authors should just list their last names
• -et-al can be added for works with many authors
• authors with entries in the _authors db should use that slug instead (e.g. just _appleton.md not _appleton-naomi.md)
• The entire title 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 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: 
from_book: 
booktitle: ""
series: 
number: 
pages: "--"
chapter: 
minutes: 
---

> 

Don't worry! You won't need to fill in every field (or even most fields) for every item. 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.

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.

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 in question.

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 where possible.

Links to Google Drive don't go here, but have a dedicated field below.

source_url

The canonical url may be undesirable if it's a redirect url (such as a DOI), a very 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 if one is available.

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 or MP3), 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 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 default.

Status

Works of especially high quality will be status: featured. For most works, simply erase this line.

Course and Tags

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