Contributors

Quire is designed to credit and add contributors to publications in a flexible way. Contributors’ data is stored in the publication.yml file of your project or in the YAML block of individual pages. The q-contributor shortcode offers multiple options to display contributors’ data in your publication. As a reminder, a shortcode is a simple snippet of code inserted in a Markdown file that pulls in information from other files in your project.

Add Contributors to Your Project

Contributors can be listed under contributor in your publication.yml file, or, for contributors specific to a page in your project, in the YAML block at the top of that page.

At minimum, each contributor must have a first_name and last_name, or just full_name. In addition to these, wherever they are listed (publication.yml or pages YAML block), the following YAML attributes can be used for your contributors:

- id:
  type:
  role:
  first_name:
  last_name:
  full_name:
  file_as:
  title:
  affiliation:
  pic:
  url:
  bio:

Display Contributors on Your Cover

Any contributor listed in your publication.yml file that has a type: primary will be considered a main author for your project and will be listed on the cover page, in the site menu, and in the metadata included in the project code. For publications with more than one author, names will be listed in the order they appear in the publication.yml file.

If the primary authors are editors of the book, you can specify that with role: editor.

Sometimes, rather than a plain list, you may want your contributors listed in a particular way. Such as, “Edited by Author Name and Author Name”. In these cases, you can add your custom text in the publication.yml file under contributor_as_it_appears which can also take Markdown and HTML tags as needed.

contributor_as_it_appears: as told by Beyoncé, Kelly Rowland,
  and Michelle Williams <br /> *with an introduction by Diana
  Ross*

While the contributor_as_it_appears value will override any contributor information otherwise listed, it is still recommended that you list the individual authors under the contributor area in your YAML, as this will be used as metadata for your book and will aid search engines and social media sites in discovering and listing your site.

Display Contributors on Individual Pages

Individual pages in your publication can have specific authors. Add them to the page YAML either with their names and other information, or by using an id that references a corresponding listing in your publication.yml file.

title: Introduction
type: page
contributor:
  - first_name: Kelly
    last_name: Roland

title: Introduction
type: page
contributor:
  - id: kroland

Contributors in the Page Heading

For most page types, you will see in previewing your site that contributors to a page will be automatically listed at the top of the page just under the title, in the order they appear in the YAML. By default, they will appear with their names and, if given, their titles and affiliations. You can override this by specifying a new value either on a page-by-page basis, or globally.

On an individual page, in the page YAML:

contributor_byline: name-title # name | name-title | false

For the entire publication, in the config.yml file:

contributorByline: name-title # name | name-title | false

While name-title is the default (and will be used if no value is specified), name will omit any title or affiliation information, and false will remove the contributor listing from the heading of the page altogether.

Just as with the cover, if you want to display the contributors in a particular way, such as “Translated by Author Name”, you can do so by specifying a contributor_as_it_appears value in the page YAML.

Contributors Elsewhere on the Page

You can also add lists of contributors to the main body of a page using the q-contributor shortcode. This allows you to create a page of contributor biographies, a section of bios for a single page, a list of contributors, a byline for a particular page, or other similar applications.

The shortcode requires both a "range" and a "format" value, and allows for an optional "align" value as well.

Sample: {{< q-contributor range="page" format="bio" align="right" >}}

The "range" value determines which contributors will be included in the list. Predefined "range" values are:

You can also use any contributor type you define. So if you give a contributor a type: primary (such as for your main publication authors, as discussed in the “Displaying Contributors on Your Cover”), then a shortcode using range="primary" will list any of your project’s primary contributors.

The "format" value determines what information will be listed for each contributor in the "range", and how it will be formatted. Possible "format" values are:

The "align" value will align the text. If no value is given, text alignment will default to the left. The possible values are:

See the q-contributor shortcode reference for details on each of the standard contributor attributes.

Sort Contributor Lists

Using the shortcode, contributors will be listed alphabetically. Either by last_name first_name if given, or full_name. You can specify a file_as value for contributors to override the default sorting.

If you wanted, for example, a list of essay contributors ordered in the way they are ordered in the page YAML block, you could assign a numeric file_as value to each (1, 2, 3 etc.). Note, though, that this file_as override will carry over to other uses of the shortcode. For example, a complete list of contributors at the end of a volume of collected papers.

Include Contributors for Search Engines

Contributor information is also embedded in Quire projects in a way that is optimized for search engine discovery. Here are a few tips to take advantage of this feature:

• List your project’s main authors in the publication.yml file and give them a type: primary
• List other contributors (like authors of individual papers) in the publication.yml file and give them a type: secondary.
• Whenever using the contributor_as_it_appears value (which overrides how contributors are listed on the cover or on individual pages) still include a list of the individual contributors in your YAML. This is especially true for your overall publication, and any pages that have a type: essay menu: false, the metadata for which is structured to pay particular attention to the authors.