Metadata & Configuration

Adjust the Default Publication Settings in config.yaml File
Add and Edit Important Metadata in publication.yaml File

Update crucial information before deploying your publication

Quire uses two YAML files as sources of the metadata and to define how the publication works. In this page, we list the YAML properties and values that need to be defined in the two following files: config.yaml and publication.yaml both of which live in the content/_data/ directory. By default, both config.yaml and publication.yaml will be generated when you create a Quire project, however the values of the properties will be either edited or added to the properties listed as we describe below.

You can read more about YAML syntax basics in YAML & Markdown.

If changes to project YAML don’t appear right away when previewing Quire, use Control-C to stop the preview and then run quire preview again.

Adjust the Default Publication Settings in config.yaml File

The config.yaml file is a required file for Quire. It is used to define a number of key values, including the location of the figure image directory, format for object entry pages, bibliography format, name of navigation buttons, contributor byline styling, and more.

Accordion Sections

For accordion sections created with the {% accordion %} shortcode, set the style of the icon used to open the section (controls); set the label texts for the section link-copying feature (copyButton); and set the label texts for the global controls created with the {% accordionGlobalControls %} shortcode (globalControls).

accordion:
  controls: arrow # arrow | plus-minus
  copyButton:
    ariaLabel: Copy page section link to clipboard
    successText: Copied page section link to clipboard
    symbol: §
  globalControls:
    collapseText: Collapse All
    expandText: Expand All

Analytics

Add your Google Analytics 4 Measurement ID to automatically add Google’s tracking codes to every page in your project.

analytics:
  googleId: ''

Bylines

Set how contributor names are listed in page headers: by name only (name); by name with their title and affiliation (name-title); or with no listing at all (false).

bylineFormat: name-title # name | name-title | false

Bibliography

Set whether bibliographies should automatically be displayed on individual pages (displayOnPage); what the label text for those bibliographies is (heading); and whether the short form of the reference should also be included with each entry in the bibliography, both for individual page bibliographies and full project bibliographies created with layout: bibliography (displayShort).

bibliography:
  displayOnPage: true
  displayShort: true
  heading: Bibliography

Citations

Set whether pop-up citations appear as text links or as icons (popupStyle); and set the text character to be used as a divider between the citation and the page number (divider).

citations:
  divider: ', '
  popupStyle: text # text | icon

Entry Pages

Set the default layout style (side-by-side or landscape) for object pages created with layout: entry (sideBySide); and set the label text for objects that appear on those pages and that have a defined link (objectLinkText).

entryPage:
  sideBySide: false
  objectLinkText: View in Collection

EPUB

Set the path to the cover image used in the EPUB file (defaultCoverImage); and the name of the directory EPUB source files are generated in (outputDir).

epub:
  defaultCoverImage: 'epub-cover.png'
  outputDir: '_epub'

Footnotes

Set the default icon for footnote backlinks.

footnotes:
  backlinkSymbol: '↩'

Figures

Set the default directories for figure images; and determine whether images should open in a lightbox modal when clicked (enableModal).

figures:
  assetDir: '/_assets/'
  enableModal: true
  imageDir: '/_assets/images'

License Icons

Set whether Creative Commons should automatically be displayed along with copyright and license information as generated by Quire.

licenseIcons: true

Localization

Defines the project’s primary language, using the ISO 639-1 language code and an optional ISO 3166-1 country code. Note that changing the language here won’t change or translate anything in Quire, it only indicates the language used in the project’s Markdown and YAML files.

localization:
  defaultLocale: en-us

Set the appearance of the contents list in the sidebar menu. Setting to brief will hide any pages with sub-sections.

menuType: full # full | brief

Set the label text for the navigation buttons that appear at the bottom of each page.

navigation:
  nextButtonText: Next
  prevButtonText: Back

Page Titles

Set the text character to be used as a divider between the label and title on pages throughout your site. While this divider may not be visible on the pages themselves, it is often used in other contexts, such as the table of contents and page metadata.

pageTitle:
  labelDivider: '. '

PDF

Set the base filename for PDF files created by Quire (filename); set the directory within the _site directory where created PDFs will be saved (outputDir); set the download links, cover page, and output for individual page PDFs (pagePDF); and set the output of full project PDFs (publicationPDF).

pdf:
  filename: 'publication'
  outputDir: '/_assets/downloads' 
  pagePDF:
    accessLinks:
      - header: true 
        label: 'PDF'
      - footer: true
        label: 'Download this page'
    coverPage: true
    output: false
  publicationPDF:
    output: true

Ref Links

Set the speed at which figure sequences and rotations move when clicked to using the {% ref %} shortcode.

ref:
  sequenceTransition: 30

Search

Set whether full-text search is enabled on the online site.

searchEnabled: true

Set the text character to be used as a divider between the page title and page contributor(s). While this divider may not be visible on the pages themselves, it is often used in other contexts, such as the table of contents and page metadata.

tableOfContents:
  contributorDivider: ' — '

Add and Edit Important Metadata in publication.yaml File

The publication.yaml file in the content/_data/ directory is the source of metadata for your publication. While the only value that is truly required is the one for the property title, it is a good idea to fill out the publication.yaml file as completely as possible. Many of the properties are used in the metadata, which is automatically included in the underlying code of every page of the online edition of your publication to support Search Engine Optimization (SEO) and general discovery.

Some key areas are summed up below, and match headings in the publication.yaml file itself, but there is a detailed documentation of individual properties and their values in the For Developers section of this guide.

Publication Base URL

The base URL is set to http://localhost:8080 by default. When you are ready to deploy your project update this value to the final URL where your publication will live (its permalink). The URL should include http:// or https:// as appropriate. See Deploy Your Project for more information.

Title & Description

Of the possible properties in this section, title, and the optional subtitle and reading_line are the most important. If your title is particularly long, the short_title property can be used to provide an alternative for the navigation elements of the online book where long titles will otherwise be truncated.

It is also a good idea to include both one_line and full descriptions, as these are used in the publication SEO metadata and often on the Cover and About or Copyright pages.

Publication Details

The values of pub_date and language should be filled out. The value of pub_date must follow a YYYY-MM-DD format (the ISO 8601 format) and should be the projected final publication date. The value of language should be a 2-letter ISO 639-1 language code. The default value is en (English) and other languages can be used.

There’s an optional pub_type property for which the possible values are book, journal-periodical, or other. If you use the value book, it is recommended you also include an ISBN as a standard identifier. If you use the value journal-periodical, you should include information for the ISSN, series_periodical_name, and series_issue_number attributes if possible.

Both ISBN and ISSN are considered if you want libraries to catalog your publication. Along with isbn and issn, doi and uuid are also supported so you can add these attributes as identifiers:

identifier:
  isbn: 978-1-12345-678-9
  uuid: 4a1b423d-6d5a-469b-bd5f-b498182ad6ca

DOIs are widely used in academic contexts to support citation while UUIDs serve to identify information in computer systems.

Note that the isbn and issn identifiers used here are for the online edition specifically. Identifiers for other specific editions (PDF/Print, EPUB, and MOBI) can be defined separately with the appropriate resource_link. See the Formats, Resources & Links section below for more.

Lastly, Quire supports publications with multiple publishers, but at least one publisher should be listed with a name, location, and url attributes. In particular, this is used in the citation features as well as in search engine metadata.

Contributors

Every publication should have at least one contributor. The contributor item type can have one of three values: primary, secondary, or project-team. The primary contributors are those who would show up on the Cover, Menu, and Title Page of a publication, and may include authors, editors, translators, and others. Contributors should, at a minimum, be listed with a first_name and last_name (or alternately just a full_name).

Additional attributes include title, affiliation, bio, url, and image. An id value can be added to the contributor information and referenced in the page YAML of individual essays or catalogue entries to indicate contributions by a particular author.

Optional contributor_as_it_appears and additional_contributors values allow for more fine-grained control in the way contributors are listed. It could be, for example, something like “Edited by Rose Valland and Denis Diderot”. Even when using contributor_as_it_appears, the contributors should still be individually listed as contributors (with a value of primary) for search engine legibility.

The editors, designers, developers, and others who worked on the title may be listed as contributors with the project-team value. This information is usually then listed on the About and Copyright pages of the publication.

Read more about this matter in the Contributors chapter of this guide.

Copyright & License

You should include a copyright line for your publication, and, optionally, license information if you are distributing the publication Open Access.

The copyright field does support Markdown to allow for multiple paragraphs and other formatting.

Open access licensing typically means applying one of seven Creative Commons Licenses to your publication. This is in addition to your copyright statement.

Note, an open Creative Commons license does not replace or supersede copyright in a work, it instead says that the copyright holder is licensing (allowing) others to make use of the work in an open way.

To use a Creative Commons license fill in the name, abbreviation, url, and scope values of the license property. The scope value should be either full, text-only, or some-exceptions and will determine the way the license is worded on your site. To override the wording and link language use the online_text and pdf_ebook_text attributes.

If the abbreviation attribute matches one of the seven Creative Commons Licenses, an icon will automatically be included, otherwise you can use the icon attribute to point to a specific image file in your images directory.

Formats, Resources, & Links

A publication can have multiple resource_link properties, each with the type of other-format, related-resource, or footer-link. These items will appear in the sidebar menu of your publication.

other-format will be where you can list the PDF, EPUB, and Paperback editions of your publication under the name attribute.
related-resource are for additional items you want to point readers to.
footer-link are links that appear at the bottom of the sidebar menu and often link to things like privacy policies, your own About page, or social media profiles.

resource_link properties can also be internal pages of the publication or files from your publication, or can point to external resources or other websites. The attributes type, name (how the resource link will be listed in your publication), and url are required.

To facilitate machine readability, it is a good idea to also include link_relation and media_type attributes from the IANA lists if applicable ones for your particular resource are available.

- type: other-format
    name: EPUB
    media_type: application/epub+zip
    link_relation: alternate
    url: /downloads/my-project.epub
  - type: other-format
    name: Paperback
    media_type: print
    link_relation: alternate
    url: https://shop.getty.edu/products/my-project
  - type: footer-link
    name: About
    link_relation: about
    url: /about/

Subjects

Any number of subjects can be added to the publication in order to aid search engine discoverability. They may be formatted as simple keywords, BISAC Subject Codes, or linked data using the Getty Vocabularies, including AAT, ULAN, and TGN.

For each subject, indicate the type: keyword, bisac, or getty. For keyword, you only need to include a single comma-separated list under the name attribute.

subjects:
  - type: keyword
    name: French painting, 19th Century, Delacroix

For all others, each subject should be listed individually and should also include an identifier attribute. For bisac subjects the identifier is the BISAC code, for the Getty vocabularies, it’s the vocabulary’s semantic URL.

subjects:
  - type: bisac
    name: "ART / European"
    identifier: ART015030
  - type: getty
    name: "Romantic"
    identifier: http://vocab.getty.edu/aat/300172863
  - type: getty
    name: "Eugène Delacroix"
    identifier: http://vocab.getty.edu/ulan/500115509

Revision History

A history of post-publication revisions made to the publication typically appears on the About page. Any number of revision history property items can be added and each must include the attributes date and a summary of changes made on that date. The summary attribute supports Markdown formatting and would typically be in list form.

If you are using GitHub or a similar service for more granular version control, you may also include the repository_url in this section. And in this case the revision history collected in the publication.yaml can act as an overview.

Improve this page

Site Title: Quire