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.yml. By default, both
publication.yml 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”.
Adjust the Default Publication Settings in config.yml File
config.yml file is a standard and required file for Definition: Hugo: The static site generator that powers Quire: https://gohugo.io/, and also for Quire. In Quire, it is used expressly for configuring how Hugo operates, and for defining a number of key values used in Quire Definition: templates: Themes may include one or more templates. Templates are the variety of layouts a theme has.. Users who have worked on other non-Quire Hugo projects will note that they typically use the
config.yml file to also store publication metadata. Given the potentially large scope of this kind of metadata in formal digital publications, Quire instead uses the
publication.yml file inside the
data directory for that purpose (see below).
The properties in the
config.yml file are individually documented in the Developers section, however, a few key items to note:
While Quire exclusively uses the
titlevalue as defined in your
publication.ymlfile, other Definition: Hugo: The static site generator that powers Quire: https://gohugo.io/ projects require a
titlevalue in the
config.ymlfile, so it is a good idea to include it here as well.
themevalue should match the name of the folder in the
/themesdirectory that contains your theme files; if you’ve copied the default Definition: theme: Themes define the overall style of your website. It determines the use of colors, layout elements, and text positioning. and given it a different name make sure to update the value here too.
paramssection includes a number of values specific to various Quire layout Definition: templates: Themes may include one or more templates. Templates are the variety of layouts a theme has. and Definition: shortcodes: A shortcode is a simple snippet of code inserted in a Markdown file that pulls in information from other files in your project. In Quire, shortcodes are used for styling, figure images, citations, bibliographies, and collaborators. Quire suports a range of shortcodes, and custom shortcodes can also be added.. All are provided with default values, and should be changed with care. In cases where a value should be deleted entirely, it is usually best to leave it as empty double quotes (
"") rather than completely deleting it.
Add and Edit Important Metadata in publication.yml File
publication.yml file in the
/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.yml 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.yml file itself, but there is a detailed documentation of individual properties and their values in the Developers section of this guide.
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.
urlshould be the final URL where your publication will live (its permalink) and should include
The value of
pub_datemust 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.
languageshould 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 whose 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
contributor_as_it_appears value allows 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 property for your publication, and, optionally,
license information property 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”.
copyrightproperty does support Markdown formatting 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.
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 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/, 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
other_formatwill be where you can list the PDF, EPUB, and MOBI editions of your publication that Quire produces.
related_resourceare for additional items you want to point readers to.
footer_linkare just that and are often links to 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.
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 a code hosting platform for version control and 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.yml can act as an overview. For more, see our revision history policy document.