Editorial work for Quire is done using a text editor,
a plain-text alternative to Microsoft Word. When editing a
Quire project you will spend all your time in the
content directory. Below we explain how to
navigate the content directory and what the
difference is between the .yaml files and the
.md files that you will encounter along the way.
Markdown
The .md files represent each page of your
project. The majority of the content found in the
.md files exist as Markdown, a human-readable way
of marking up text with symbols and code that will easily
convert to HTML. For example, in Markdown, two asterisks
surrounding a word will cause it to appear in
bold (**bold**). Learn more
about Markdown in the
YAML & Markdown
section of the Quire documentation.
YAML
In Quire publications, some parts of the text function as
data. This text is treated as data because it can be found in
multiple places throughout the publication. Rather than
re-entering that information each time it appears, Quire has
been designed to simplify this process by storing the
information as YAML. YAML is primarily used for publication
metadata (title, subtitle, contributors), page information
(essay title, essay subtitle, contributors) and objects. YAML
files (indicated by the suffix .yaml) can
primarily be found in the _data folder of the
content directory. A block of YAML is also include at the top
of every .md file. YAML can also be used in
tandem with shortcodes to pull figure images and citations
into your .md files. Keep reading to learn more.
Shortcodes
The data found in YAML is regularly made use of with
shortcodes. A shortcode is a simple snippet
of code inserted in a .md file by the Quire team.
The shortcode pulls in information from your data files using
an identifier (id). This means that, in most
cases, when you edit a YAML file, these changes will be
automatically be reflected in all Markdown files that include
a shortcode with a matching id. Shortcode
examples explored below include {% figure %} for
figure images, {% cite %} for references, and
contributors {% contributor %}.
Publication.yaml
The publication.yaml file includes all the
metadata for your publication (its title, subtitle,
contributors, publication date, etc.) This information is used
for search engine optimization (SEO), as well as on the site
itself in headings, navigation labels, and on your About or
Copyright page.
Page YAML
Page YAML includes essay title, subtitle, page order,
contributor information, etc. If, for example, you need to
make a change to an essay title that appears in the top
navigation, sidebar menu, contents pages, running footer, or
the essay itself, that change will need to be made in the
essay .md file. You can find the YAML listed at
the very top of the page surrounded by two sets of three
dashes, as in the example below.
---
title:
short_title:
order:
layout:
contributor:
first_name:
last_name:
---
If an essay title is too long, it may be truncated in the top
navigation. If this happens, you need to add a
short_title to the page YAML.
Page YAML also interacts with shortcodes. For example, the
{% contributor %} shortcode pulls the contributor
bio information found in the page YAML of each essay. This can
be used to create a contributors page in the backmatter of
your publication.
Objects.yaml
Information on catalogue object metadata including artist
name, artwork year, dimensions, medium, location, link to
work, etc. is stored in the objects.yaml file.
Object information is pulled into the catalogue pages by the
inclusion of an object id in the page YAML.
---
title: "Long title "
short_title: "Title"
order: "2"
layout: "entry"
object:
- id: "01"
---
The page YAML above corresponds with the id found
in the objects.yaml file. That means that all the
data listed in the object.yaml, related to the
object with the id “01”, would be pulled in the
.md file that includes that page YAML.
object_list:
- id: "01"
title: "Object name"
maker: "Artist/maker name"
place_date: "Place and date where it was made"
medium: "Medium of object"
dimensions: "Size of object"
accession_number: "Accession number"
link: "Link to collection website"
figure:
- id: "1-1"References.yaml
Bibliographic information lives in the
references.yaml file.
- id: "Doe 2020"
full: "Full citation for Doe 2020"(Note: “Full” should appear lined up with “id” in the correct YAML syntax. Failing to properly indent will result in a preview error.)
Sometimes the presence of diacritics, lowercase names, or two
author names in a citation may affect the proper ordering of
your references. If you need to change the order that
bibliographic entries appear in, the order can be overwritten
by adding a sort_as value to the
references.yaml
If a publication includes pop-up citations and appears to have
missing bibliographic entries, there are most likely incorrect
or missing {% cite %} shortcodes in the essay end
notes. You can find those in the essay Markdown file. The
quoted text that follows {% cite %} should
exactly match the id in the
references.yaml files. Any changes made to a
bibliographic citation should be made first to the
references.yaml file, and then to every instance
of that citation throughout the text. Failure to make changes
in all places will result in broken links.
- id: "Doe 2020"
full: "Full citation for Doe 2020" (Note: “Full” should appear lined up with “id” in the correct YAML syntax. Failing to properly indent will result in a preview error.)
{% cite "Doe 2020" %}
The {% cite %} shortcode also plays an important
role when generating a bibliography. So a missing or
misspelled {% cite %} shortcode will result in
the entry entry being left out of the bibliography completely.
The best way to prevent missing
{% cite %} shortcodes is by properly tagging
the text prior to transmittal to the Quire team. For more
information on the correct tags to use see the
Manuscript Prep
section of this guide.
Figures.yaml
Information for figure images including caption, credit, and
alt text can be found in the figures.yaml. The
Quire team then uses the the
{% figure %} shortcode to insert images along
with their captions in the body of the text.
- id: "1-1"
src: "figures/fig-1-1.jpg"
label: "Fig. 1.1"
caption: "Caption for images 1.1"{% figure "1-1" %}
The one exception to how caption information is pulled into
the text from the the figures.yaml is when two
images share a single caption. You can override the appearance
of two separate captions by adding the caption text directly
into the shortcode. This will override the
figures.yaml and cause the two images to be
displayed together with one caption.
Exceptions
Information TK on using Liquid to pull information in from
publication.yaml into
copyright.md and about.md files.