Quire Workshop

About Quire

Quire is an open-source publishing tool developed by Getty that is used to create long-lasting and discoverable publications. It is not a publishing service or a platform for hosting publications. Instead, Quire provides its users (students, researchers, professors, curators, editors, and more) with the ability to produce multimedia-rich scholarship for the web. The same set of files used to create the website can also be used to create a PDF, e-book, and print book. Quire is an excellent option for long-form book-like projects, especially those that rely on visual illustrations and scholarly elements like citations, bibliographies, and footnotes. Quire is freely available for anyone who wants to use it. You can learn more at http://quire.getty.edu.

Examples of Quire Publications

• 

  Materia: Journal of Technical Art History

  Journal | 2024

  Quire user: @materiajournal

  More View

• 

  Yale University Art Gallery

  Collection Catalogue | 2023

  Quire users: @tiffanysprague @zsofiaj

  More View

• 

  Museum Studies at the George Washington University

  Essay Collection | 2022

  Quire users: @shineslike @gealbers

  More View

• 

  Getty Foundation

  Report | 2020

  Quire user: @geealbers

  More View

Quire Benefits & Challenges

About this Workshop

The workshop seeks to break down the various tools, formats, and processes necessary for using Quire into approachable and easy-to-understand concepts. We will additionally provide attendees with step-by-step exercises to help them gain confidence in navigating and using the tool. We aim for individuals who take this workshop to leave feeling excited to continue experimenting and creating.

Part 1: Basic Concepts: Command-Line Interface & Text Editor
Part 2: Basic Concepts in Action
Part 3: Going Deeper: YAML
Part 4: Going Deeper: Images
Part 5: Going Deeper: Shortcodes
Part 6: Going Deeper: Customization

If we don’t cover everything during the four hours allotted for the in-person workshop, we invite people to continue exploring Quire independently by following the syllabus below.

Before Getting Started

1. Install Quire: https://quire.getty.edu/docs-v1/install-uninstall/
2. Install Visual Studio Code, a free text-editor: https://code.visualstudio.com/

Part 1. Basic Concepts

In this section, you will learn about and get hands-on experience with the two main tools that are required to use Quire: the command-line interface (CLI), which is used to navigate your project and tell Quire what processes to run, and the text editor, which is the tool used to organize, write, and edit your project files.

Learning to Love the Command-Line Interface

What is the command-line interface?

A command-line interface (CLI) is a text-based interface used to run program tasks. It is operated through a command-line shell which is referred to as “Terminal” on a Mac and “Powershell” on a PC. The CLI enables the user to type commands as strings of text into the shell. This is opposed to a graphical user interface (GUI), in which the user controls the program through visualized buttons, toggles, and menus.

When you install Quire, what you are actually installing is the Quire CLI.

This is what the command-line shell looks like when it is first opened on a Mac computer:

What are the benefits of using the command-line interface?

The main benefit of the CLI is efficiency. Instead of spending time finding and clicking on individual files, you can use the CLI to perform actions on several files with simple text commands. Additionally, CLI applications often consume fewer network resources compared to graphical applications. It’s worth noting that the CLI is a powerful tool; however, it is used in a very basic, straightforward way when working on Quire projects, so don’t be intimidated!

Navigating with the CLI

One of the primary functions of the CLI is to easily navigate files on your computer. In the exercise below, you will use commands like cd (“change directory”) and ls (“list”) to explore your computer’s home directory, the main storage folder that contains your personal files. You will then use Finder/Explorer to do the same thing.

Learning to Love the Text Editor

You can think of your text editor, like the free tool Visual Studio Code, as a supplement to Microsoft Word. A text editor is used to create, change, or edit plain-text files. The beauty of plain-text files is that they do not require proprietary software. Therefore, content is written in a way where, should certain technology go obsolete, your content will remain stable and accessible. The text editor is your primary interface for working on your Quire project, so getting comfortable with it is essential. It is especially important to familiarize yourself with Markdown, the format used for your project’s more narrative/textual content.

What is Markdown?

Markdown might seem strange initially, but it is a very approachable language that uses simple character combinations to indicate structure and add formatting elements (headings, bulleted lists, URLs). Rather than using buttons to format the appearance of your text, as you would in Microsoft Word, you are using symbols instead. Quire then does the heavy lifting and converts those symbols into HTML for you. For example, something surrounded by asterisks in Markdown turns into italics in the final publication: emphasis = emphasis.

What are the benefits of using Markdown?

Markdown was designed for readability and is not heavily marked up with tags like other coding languages.

A list written in HTML:

<h2>An Unordered HTML List</h2>

<ul>
  <li>Coffee</li>
  <li>Tea</li>
  <li>Milk</li>
</ul>  

The same list written in Markdown:

## An Unordered HTML List

- Coffee
- Tea
- Milk 

The fact that Markdown is preserved in a human-readable format makes it very easy to edit and it also helps preserve the longevity of your content.

Part 2. Basic Concepts In Action

Now that you understand two of the most fundamental tools needed to use Quire, it’s time to get a new project up and running and implement these basic concepts.

Use the CLI to Start and Preview a New Quire Project

In addition to using the CLI to navigate Quire, as we explored earlier, it can also be used to tell Quire what to do, including creating a new project, previewing a project, or outputting a website, PDF, and e-book. In the steps below, we will use the CLI to create a new project, navigate into that project’s folder, and preview it.

Please note: The command quire new generates a default starter project. It is a sample publication meant to serve as a jumping off point. It serves as a useful template with images and text that can be delete or substituted when creating your own project.

Open Your Project with Visual Studio Code

Now that you have your new project up and running, it’s time to edit it! First, we must open the project with our text editor and familiarize ourselves with the file structure.

This is what the default starter project will look like it is first opened in your Text Editor.

Navigating Files with Visual Studio Code

The “content” folder is where pretty much all the action takes place. The most important files/folders within “content” are the following:

Making Edits with Visual Studio Code

Let’s take a closer look at a Markdown files (indicated by .md) and make some simple edits based on what we learned in Part 1.

You can use this page of the Quire documentation as a reference: http://quire.getty.edu/docs-v1/fundamentals/#markdown-basics.

Part 3. Going Deeper: YAML

In addition to Markdown, YAML is the other format in which you will save content in Quire. YAML plays many roles in your quire project, including storing important publication information like title, subtitle, authors, chapter titles, captions, references, and more.

Learning to Love YAML

What is YAML?

YAML stands for “YAML Ain’t Markup Language”. YAML is also written in a plain-text, human-readable format, and its primary purpose is to save text/content as data. It’s less about how the content is written and more about how and where the information is saved in your project. YAML is formatted as the name of a data item, followed by a colon, a space, and then the data item’s value.

Here is an example of how YAML is formatted:

title: My Project

What are the benefits of using YAML?

YAML provides a way of capturing information that appears in multiple places throughout your project and is therefore treated like data. This prevents you from needing to write things multiple times. YAML is also considered easier to read and write than other data-specific formats, like JSON, especially for non-developers.

Page YAML

Every page of content in your Quire publication must start with a block of YAML. You can identify the YAML because it appears between a set of three dashes at the top of each .md file. The three YAML keys that must appear on every page are: title, layout, and order.

---
title:
layout:
order:
---

Let’s look at the intro.md file as an example. This is the YAML block that appears at the top of that page:

---
title: Introduction
subtitle: A Tale of Two Photographers
layout: splash
order: 10
image: figures/lange-house.jpg
---

The title is the title of the essay, the layout affects the format of the page, and order affects the page order of the publication. Let’s rename the “Introduction”.

publication.yaml

Another role YAML plays in your project is storing important metadata. This information is kept in the publication.yaml file and includes things like publication title and contributors, copyright information, BISAC codes, publisher, CC license, revision history , etc. The data in this file is automatically included in the underlying code of every page of your project’s online edition, supporting Search Engine Optimization (SEO) and general discovery.

The publication.yaml file lives in the _data folder along with several other YAML files such as figures.yaml, objects.yaml, and references.yaml. We will look at those files a little later on. For now, our focus is just on the publication.yaml file.

publication.yaml Continued

As previously mentioned, YAML stores information that is used in multiple places throughout your project. The publication.yaml file is a good example of that. For example, the only place the title of your Quire project lives is in this file, but that title is used on the project’s cover page, the sidebar menu, in the e-book and PDF version of your publication, and in metadata used for SEO and discovery.

Part 4. Going Deeper: Images

Now that we have changed the title of your Quire project, let’s also change the cover image.

Where images are stored

The images that comprise your Quire project live in the _assets folder in a subfolder called images.

Adding new images to your project

Images can be easily added and subtracted from your Quire project. When adding new images they should be placed in the images folder. There are a few ways to add images to your Quire project. The first is by incluing image: and the title of your image file in your page YAML.

Part 5. Going Deeper: Shortcodes

The second way to include images in your Quire project is by using shortcodes.

Learning to Love Shortcodes

What are shortcodes?

A shortcode is a simple snippet of code inserted in a .md file that pulls in information from other files in your project. In Quire, shortcodes are used to insert figure images, citations, object information, and more.

What are the benefits of using shortcodes?

Shortcodes save a lot of time and energy. Rather than repeating lengthy information in multiple places throughout your project, you can use a shortcode as a shortcut. A shortcode usually references an id. For example, the shortcode below is referencing a figure (an image) that has been assigned the id fig-1.

{% figure 'fig-1' %}

That id is associated with an image file, caption, credit, label, etc.

When you insert that shortcode into a .md file, you will automatically see the image file, caption, credit, label, etc., when you preview that page in your browser.

Here is an example of a shortcode being used in the preface.md to pull in a figure with the id: fig-1:

figures.yaml

The id is assigned in the figures.yaml file. This is where you also store information like the image file, caption, credit, label, alt text, etc. As we mentioned before, the beauty of YAML is that you store information in one place and can reference it in multiple locations in your publication. This also means that if you edit a figures caption, rather than changing it everywhere the figure appears in your publication, you only need to update it in the figures.yaml file.

Here is an example of a figures.yaml entry:

• id: “fig-2” label: “Figure 2” src: figures/evans-sons.jpg caption: “Walker Evans. Sons of the American Legion, Bethlehem, Pennsylvania, 1935.” credit: “The J. Paul Getty Museum, Los Angeles”

The src is the path for where the image is stored in the Quire project. In this case, the image evans-sons.jpg lives in a folder called figures. This folder is inside the images folder. You can use subfolders to help organize your images; just be sure to include the folder name in the src path.

Inserting the image

Inserting a new image is a three-step process. First, save the image in the _assets/images/ folder. Next, you must create an entry for that image in the figures.yaml file and assign the image an id. Finally, decide where in the relevant .md file you want the image to appear and enter a shortcode with the assigned id.

Part 6. Going Deeper: Customization

There are several ways to customize your Quire project with varying degrees of difficulty.

To make Quire approachable to everyone, regardless of technical experience, we’ve added built-in style variables that allow for relatively easy customizations.

Learning to Love Style Variables

What are style variables? Variables are essentially a list of built-in options for making style customziations. You can use them to control things like text and background colors, specific element sizes, fonts, paragraph indents, PDF margins, and more.

What are the benefits of using style variables?

While the style variables have a limited range of customizations you can make, they still give you a lot of flexibility when it comes to changing the look and feel of your project without needing to learn CSS/HTML or going deeper into the code and making code changes in the stylesheets.

Editing Style Variables

The style variables are located in the _assets folder, in a subfolder called styles. There, you will find a file called variables.scss.

Variables are prefixed with a dollar sign and are descriptive of what they control. For instance, $content-background-color changes the background color of the main content area. The following variable would make the background color appear light grey:

$content-background-color: LightGrey;

Here is a list of the variables defined in Quire and what they control: https://quire.getty.edu/docs-v1/variables/#defined-variables.

Here is an example of customizations made to the default starter project using the style variables:

Next Steps

You can continue reinforcing the concepts above by creating a new page in your Quire project.

If you get stuck at any point, please refer to the Quire documentation for assistance.

Advanced Quire

Coming soon . . .