Metadata & Configuration
Update crucial information before deploying your publication
Quire uses two Definition: YAML: YAML is a plain-text, human-readable format for writing and storing data. YAML can be used in a standalone file with the file suffix
yml, or inside a Markdown (
.md) file. Read more in the Fundamentals: YAML & Markdown chapter of this guide. 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:
publication.yaml both of which live in the
content/_data/ directory. By default, both
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
Adjust the Default Publication Settings in config.yaml File
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. These properties are individually documented in the For Developers.
Add and Edit Important Metadata in publication.yaml File
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 Definition: Search Engine Optimization (SEO): Search engine optimization, SEO, is the process of increasing the online visibility of a website or a web page in a web search engine’s unpaid results. 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
https:// as appropriate. See Deploy Your Project for more information.
Title & Description
Of the possible properties in this section,
title, and the optional
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
full descriptions, as these are used in the publication SEO metadata and often on the Cover and About or Copyright pages.
The values of
language should be filled out. The value of
pub_date must follow a YYYY-MM-DD format (the Definition: ISO 8601 format: ISO 8601 describes an internationally accepted way to represent dates and times using numbers. More information about the format can be found at the ISO website: https://www.iso.org/iso-8601-date-and-time-format.html) and should be the projected final publication date. The value of
language should be a 2-letter Definition: ISO 639-1 language code: ISO 639 is the International Standard for language codes. More information about the standard can be found at the ISO website: https://www.iso.org/iso-639-language-codes.html. 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
other. If you use the value
book, it is recommended you also include an Definition: ISBN: The International Standard Book Number, or ISBN, identifies books or book-like products, as well as their publishers. There is one ISBN agency per country, the U.S. ISBN Agency can be found at: https://www.isbn.org/ as a standard
identifier. If you use the value
journal-periodical, you should include information for the Definition: ISSN: The International Standard Serial Number, or ISSN, identifies newspapers, journals, magazines and periodicals of all kinds and on all media–print and electronic. For more information visit: https://www.issn.org/,
series_issue_number attributes if possible.
Both Definition: ISBN: The International Standard Book Number, or ISBN, identifies books or book-like products, as well as their publishers. There is one ISBN agency per country, the U.S. ISBN Agency can be found at: https://www.isbn.org/ and Definition: ISSN: The International Standard Serial Number, or ISSN, identifies newspapers, journals, magazines and periodicals of all kinds and on all media–print and electronic. For more information visit: https://www.issn.org/ are considered if you want libraries to catalog your publication. Along with
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
Definition: DOIs: The digital object identifier (DOI) is a unique alphanumeric string that identifies content and provides a persistent link to its location on the Web. DOIs are assigned the International DOI Foundation: https://www.doi.org/ are widely used in academic contexts to support citation while Definition: UUIDs: A universally unique identifier or UUID is a 128-bit number used to identify information in computer systems serve to identify information in computer systems.
- Note that the
issnidentifiers 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
url attributes. In particular, this is used in the citation features as well as in search engine metadata.
Every publication should have at least one
type can have one of three values:
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
last_name (or alternately just a
Additional attributes include
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.
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 Definition: Open Access: Open access (OA) refers to free, unrestricted online access to content, frequently research outputs..
A simple Definition: Copyright: Copyright is a form of protection granted by law for original works of authorship fixed in a tangible medium of expression. For more information about U.S. copyright visit: https://www.copyright.gov/help/faq/faq-general.html#what statement would typically be formatted as “© 2019 Author Name”.
copyrightfield does support Markdown to allow for multiple paragraphs and other formatting.
Open access licensing typically means applying one of seven Definition: Creative Commons Licenses: Creative Commons licenses are public copyright licenses that enable the free distribution of a work. Every license helps creators retain copyright while allowing others to copy, distribute, and make some non-commercial uses of their work. You can check the different types of Creative Commons licenses at: https://creativecommons.org/about/cclicenses/ 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
scope values of the license property. The
scope value should be either
some-exceptions and will determine the way the license is worded on your site. To override the wording and link language use 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
footer-link. These items will appear in the sidebar menu of your publication.
other-formatwill be where you can list the PDF, EPUB, and Paperback editions of your publication under the
related-resourceare for additional items you want to point readers to.
footer-linkare 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
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
media_type attributes from the Definition: IANA: Internet Assigned Numbers Authority (IANA) is responsible for coordinating Internet’s globally unique identifiers. DNS Root, IP addressing, and other Internet protocol resources are performed as the Internet Assigned Numbers Authority (IANA) functions. For more information visit:https://www.iana.org/ 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/
Any number of subjects can be added to the publication in order to aid search engine discoverability. They may be formatted as simple keywords, Definition: BISAC Subject Codes: Developed by BISG, the BISAC Subject Codes List, or BISAC Subject Headings List, is a standard used to categorize books based on topical content. For more information visit: https://bisg.org/page/BISACSubjectCodes, or linked data using the Definition: Getty Vocabularies: Controlled vocabularies developed to ensure consistency in cataloging and more efficient retrieval of information. For more information visit: https://www.getty.edu/research/tools/vocabularies/, including AAT, ULAN, and TGN.
For each subject, indicate the
keyword, you only need to include a single comma-separated list under the
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
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 Definition: GitHub: GitHub is project management platform built around git version control and optimized for team collaboration. For an introductory guide to it, visit: https://guides.github.com/activities/hello-world/#what 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.