Hands-On 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: References
Part 7: Going Deeper: Customization

If you are interested in having a hands-on Quire workshop led by a Quire representative either in person or virtually, please contact quire@getty.edu.

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. This demonstrates how running commands in the command-line shell mirrors the process of clicking through folders in your Finder/Explorer.

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

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 deleted 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 when 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 file and make some simple edits based on what we learned in Part 1.

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’s primary purpose is to save text/content as data. When it comes to YAML, it’s all about how that information is formatted. It is always written as a data item followed by a colon, a space, and then the data item’s value.

Here is an example:

title: "My Project"

You can also use Markdown when storing information as YAML:

title: "*My Project*"

We advise always wrapping YAML values in quotations.

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 information, 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.

When making changes to .yaml files it’s necessary to stop and restart the preview for the change to become active/visible.

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 _assets/images/ folder. Once the images have been saved, there are a few ways to add them to the pages of your Quire project. The first is by incluing image: and the title of your image file in the 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, glossary terms, 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 image that has been assigned the id fig-1.

{% figure 'fig-1' %}

When you insert the shortcode {% figure 'fig-1' %} into a .md file, you will automatically the image that has been assigned the id fig-1 appear 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. In the figures.yaml file you store the path to the image file as well as the caption, credit, label, alt text, etc. Each image and its related data is assigned an id. As we mentioned before, the beauty of YAML is that you store information in one place and can reference it in multiple locations throughout your publication using the id. This also means that if you edit a image’s caption, rather than changing it everywhere the image appears in your publication, you only need to update it in the figures.yaml file and it will automatically update everywhere the id is used in a shortcode.

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 is a subfolder inside the images folder. You can use subfolders to help organize your images; just be sure to include both the folder and subfolder 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 what .md and where within that file you want the image to appear. Then enter a shortcode that references the assigned id.

Part 6. Going Deeper: References

YAML can also be useful when it comes to creating a bibliography or adding pop-up citations to your project. All bibliographic information for your publication is stored in the references.yaml file located in the _data/ folder.

Each entry in the references.yaml file must include the full form of the bibliographic reference and an id.

  - id: "Evans 1938"
    full: "Evans, Walker. *American Photographs*. New York: Museum of Modern Art, 1938."

As in the example above, the id would typically be the short form of the reference in Author Date format. Note that unlike the figures.yaml file, the id used for references can have spaces. The way the id is written is how it will appear in both the bibliography and clickable text for the pop-up citation.

Creating a Bibliography

In the default starter project there is a file called bibliography.md. When looking at the page YAML you’ll notice there is a special layout type of bibliography. A .md file with this layout type will automatically pull in the information found in the references.md file and sort it alphabetically.

Inserting pop-up citations

Similar to inserting images with shortcodes, you can also use a shortcode to insert pop-up citations. This is an example of what a citation shortcode looks like:

{% cite 'Evans 1938' %}

When the shortcode is added to a .md file, the same text that is used as the id appears underlined, indicating that it can be clicked on. When you click on the underlined text, the content stored in the full portion of the YAML entry appears.

In addition to adding the reference information as a pop-up citation, it will also appear as an entry in a page-level bibliography.

Part 7. 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 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 a customization (the addition of rosy pink at the top of the page) 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…

GitHub

Please see the GitHub section of our website for a tutorial.