Adding new tags

For a current view of all our tags, see the tag ontology page.

Below you'll find the life cycle of a tag:

1. Content tag

The first step to adding a new tag, is simply to add the tag as a tag: item on a work. Keep in mind that these tags will later have to be _tags/[tagid].md slugs, so they must be lowercase with hyphens instead of spaces.

Content tags appear in the table at the bottom of the ontology page along with a count of the number of works using that tag. Content tags are used by search and the item similarity engine, but are only shown to the end user via the bibtex export.

2. Unpublished tags

The next stage is to create a bare minimum tag entry. This will create a hidden tag page that you can access by going directly to the URL (/tags/[tagid]). It will also add the tag's node to the directed ontology graph (clicking on the node will also take you to the unpublished tag page).

At minimum, please fill out:

---
title: "Subject Matter"
status: unpublished
parents: [supertopic, hypernym]
---

This will allow the ontology viewer to properly add your node to the tree.

3. Release candidate

When a tag's corresponding Drive folder has been added to the site, the tag is ready for review.

At this time, add all the information needed to the tag for it to render properly, such as the description and images.

Images

Adding images is a bit complex. It must be done in two stages (Sirv and then GitHub) and is slightly different between the Illustration at the top of the tag page and the Footer at the bottom.

Begin by uploading your image(s) in high or moderate resolution to Sirv, then add the following metadata to the tag's header:

Illustrations

Illustration metadata looks like the following:

use_sirv: true
illustration: https://illeakyw.sirv.com/Images/tags/whatever.jpg
illustration_height: 636
illustration_width: 1024
illustration_center_x: 25%
illustration_center_y: 20%
illustration_caption: >-
  An image to illustrate the meaning of this tag and a caption which explains the photo and its relationship with the topic.
  (<a href="https://commons.wikimedia.org/wiki/File:original.jpg">Author</a>, <a href="https://creativecommons.org/licenses/by-sa/4.0">CC BY-SA 4.0</a>)

These files should be at least 500x500 pixels.

Footer banners

These are the hero images at the bottom of any page. To add one, add these fields:

image: https://illeakyw.sirv.com/Images/banners/whatever.jpg
image_width: 1024
image_height: 683
# big_image: https://upload.wikimedia.org/wikipedia/commons/6/69/original_file.jpg
# big_height: 1024
# big_width: 1650
footer_info: <a href="https://commons.wikimedia.org/wiki/File:source_file.jpg">Author</a>, <a href="https://creativecommons.org/licenses/by/2.0">BY 2.0</a>
image_center_x: 39%
image_center_y: 51%

These files should be at least 1024p wide.

big_height is actually optional at the moment, but big_width is not after launch, so it's best to include them both. Note also that these fields are commented out for now!

Adjustments

Now you can render the site and it will pull the images from Sirv and render you tag exactly as it will when published. Use this time to make adjustments to the center values of the images and to confirm that you want to use these images after all.

Also use this time, of course, to review the contents of the tag. Remove things that were misplaced, add any items that are missing, and generally make sure it's a well-rounded bibliography.

4. Release

When you're ready to release the tag, make sure to add the images to the production environment first.

Productionizing the images

1. In the imgs repository, add the illustration image from Sirv to ./tags/tags/ in a separate branch and
2. add the center values as [x,y] to tags/image_metadata.json
3. Squash and merge these two changes to imgs:master.
4. In the big_img repo, add the big image file to ./banners/footers/ in a new branch with the same filename as the image: (but not necessarily the same size, just use "big_size" fields) and then
5. add the center [x,y] data to ./banners/image_metadata.json.
6. Squash and merge those two changes to big_imgs:main
7. Remove the use_sirv: true field from the tag.md to allow it to use the derived illustration images and
8. uncomment the big_* fields from the tag.md file to tell Jekyll it can now use the big_img banner versions.

Congratulations! The tag should now be using the production-ready webm images instead of the Sirv images.

Publish ("soft launch") the tag

Next, change status: unpublished to status: published to make the tag publicly visible.

This will add the tag to the main /tags index page and will add tag links to the bottom of any tagged work in the library.

Published tags appear as bolded in the ontology viewer.

Announcement

After some additional QA, announce the launch on Mastodon and prepare an email to subscribers.

Congratulations! There's now a new section in the library 🤓