Author "roles" column and affiliation "position" field in HTML title block metadata

[luifrancgom]

Description

I want to know if it is possible to add a column between author and affiliation in the HTML title block metadata, and to add a "position" field to affiliation to specify the author's position(s) related to that affiliation.

Expected behavior

See the following minimal reproducible example and the following GitHub repository

Use cases

Roles

When generating a book, you can have the following use cases:

• Author 1 was the original author
• Author 2 was the translator

When writing a document in an organization or in an academic environment, you want to specify your role in building it:

• Author 1 was in charge of the formal analysis
• Author 2 was in charge of writing the document
• Author 3 was in charge of converting the document into different formats (PDF, HTML, ODT, or DOCX)

Position

When generating a document, you sometimes need to specify at least one position (role/title) in the organization to which you are affiliated.

Feasibility

Roles

Many of the necessary components have already been developed in Quarto, in Roles via authors.lua, including the possibility to add the Contributor Role Taxonomy (CRediT).

However, this feature has not been directly integrated into any of the formats, nor does it take advantage of other Quarto functionalities, such as changing the label depending on whether there is one author or more than one (e.g., "Role" vs. "Roles") in the way it already does for author and affiliation.

I also checked whether this could potentially affect the current layout, using the minimal reproducible example and the GitHub repository, in the following cases:

Missing items

Without affiliation but with role

Without role but with affiliation

Neither of them

Position

In authors.lua the following aspects could potentially be used:

lua constant	lua value	yaml
kId	'id'	id
kAffilName	'name'	name
kDepartment	'department'	department
kGroup	'group'	group
kAddress	'address'	address
kCity	'city'	city
kRegion	'region'	region, state
kCountry	'country'	country
kPostalCode	'postal-code'	postal-code
kUrl	'url'	url, affiliation-url
kISNI	'isni'	isni
kRinggold	'ringgold'	ringgold
kROR	'ror'	ror

But there is nothing related to "position" that can be used directly, at least not in a template extension, even though this is sometimes needed. I don't know if something like kPosition, 'position', and position could be implemented based on Combinations in authors.lua, so that it could be added like this:

author:
  - name: author 1
    affiliation:
      - name: affiliation 1.1
        position:
          - position 1.1.1
          - position 1.1.2
      - name: affiliation 1.2
        position:
          - position 1.2.1
  - name: author 2
    affiliation:
      - name: affiliation 2
        position:
          - position 2.1
          - position 2.2

[mcanouil]

Both fields already reach the template today, so this needs no change in Quarto.

roles: is normalised into by-author[].roles[].
Each entry holds role and degree-of-contribution, and a CRediT term also gets vocab-identifier, vocab-term, and vocab-term-identifier.

• quarto-cli/src/resources/filters/modules/authors.lua

  Lines 719 to 782 in abc6a78

  	local function setRole(author, role)
  	if not author[kRoles] then
  	author[kRoles] = {}
  	end
  	-- resolve shorthands
  	local term = string.lower(role.role)
  	local alias = kCreditAliases[term]
  	if alias then
  	term = alias
  	end
  	-- if this is a CreDiT Role then
  	-- attach vocabulary decorations
  	if tcontains(kCreditRoles, term) then
  	role[kVocabIdentifier] = kCreditVocabIdentifier
  	role[kVocabTerm] = term
  	role[kVocabTermIdentifier] = kCreditVocabTermIdentifiers[term]
  	end
  	author[kRoles][#author[kRoles] + 1] = role
  	end
  	local function parseRole(role)
  	if pandoc.utils.type(role) == 'Inlines' or pandoc.utils.type(role) == 'Inline' then
  	-- this is just a simple string representing the role
  	return pandoc.utils.stringify(role)
  	else
  	for k,v in pairs(role) do
  	return pandoc.utils.stringify(k), pandoc.utils.stringify(v)
  	end
  	end
  	end
  	local function setDegree(author, degree)
  	if not author[kDegrees] then
  	author[kDegrees] = {}
  	end
  	author[kDegrees][#author[kDegrees] + 1] = degree
  	end
  	-- Processes author roles, which can be specified either using `role:` or `roles:`
  	-- and can either be a single string:
  	-- role: researcher
  	-- or an array of strings:
  	-- roles: [researcher, writer]
  	-- or one or role objects with key role, value degree of contribution
  	-- like:
  	-- roles:
  	-- - researcher: lead
  	-- - writer: supporting
  	-- general in support, but derived a bit from
  	-- https://credit.niso.org
  	local function processAuthorRoles(author, roles)
  	if tisarray(roles) then
  	for i,v in ipairs(roles) do
  	local role, contribution = parseRole(v)
  	setRole(author, { [kRole] = role, [kDegreeContribution] = contribution })
  	end
  	else
  	local role, contribution = parseRole(roles)
  	setRole(author, { [kRole] = role, [kDegreeContribution] = contribution })
  	end
  	end

position: needs no kPosition constant.
An affiliation key that Quarto does not know is not dropped.
It goes under metadata, so a template reads it as by-author[].affiliations[].metadata.position.

• quarto-cli/src/resources/filters/modules/authors.lua

  Lines 367 to 383 in abc6a78

  	local function processAffilationObj(affiliation)
  	local affiliationNormalized = {}
  	affiliationNormalized[kMetadata] = {}
  	for affilKey, affilVal in pairs(affiliation) do
  	if (tcontains(tkeys(kAffiliationAliasedFields), affilKey)) then
  	affiliationNormalized[kAffiliationAliasedFields[affilKey]] = affilVal
  	elseif tcontains(kAffiliationFields, affilKey) then
  	affiliationNormalized[affilKey] = affilVal
  	else
  	affiliationNormalized[kMetadata][affilKey] = affilVal
  	end
  	end
  	return affiliationNormalized;
  	end

The same fallback exists for an unknown key directly under an author.

• quarto-cli/src/resources/filters/modules/authors.lua

  Lines 1009 to 1014 in abc6a78

  	else
  	-- since we don't recognize this value, place it under
  	-- metadata to make it accessible to consumers of this
  	-- data structure
  	setMetadata(author, authorKey, authorValue)
  	end

A small example

Here is a project that shows both, with one partial and no Lua filter:

• https://github.com/mcanouil/quarto-issues-experiments/tree/main/quarto-cli-14776

It replaces title-metadata.html, which holds the whole author and affiliation grid.
The heading row gains one cell, and each author row gains one cell:

<p class="roles">$for(by-author.roles)$$it.role$$if(it.degree-of-contribution)$ ($it.degree-of-contribution$)$endif$$sep$, $endfor$</p>

$if(it.metadata.position)$<span class="affiliation-position">$it.metadata.position$</span>$endif$

The example also covers the four layouts in your screenshots: roles without an affiliation, an affiliation without roles, neither, and no affiliation at all.

The singular and plural label

The author and affiliation headings need no work.
computeLabels selects the singular or the plural string, so $labels.authors$ and $labels.affiliations$ are correct in every language that Quarto ships.

• quarto-cli/src/resources/filters/modules/authors.lua

  Lines 853 to 877 in abc6a78

  	local function computeLabels(authors, affiliations, meta)
  	local language = param("language", nil);
  	if not _quarto.format.isAstOutput() then
  	meta[kLabels] = {
  	[kAuthorLbl] = {pandoc.Str("Authors")},
  	[kAffiliationLbl] = {pandoc.Str("Affiliations")}
  	}
  	if #authors == 1 then
  	meta[kLabels][kAuthorLbl] = {pandoc.Str(language["title-block-author-single"])}
  	else
  	meta[kLabels][kAuthorLbl] = {pandoc.Str(language["title-block-author-plural"])}
  	end
  	if meta[kAuthorTitle] then
  	meta[kLabels][kAuthors] = meta[kAuthorTitle]
  	end
  	if #affiliations == 1 then
  	meta[kLabels][kAffiliationLbl] = {pandoc.Str(language["title-block-affiliation-single"])}
  	else
  	meta[kLabels][kAffiliationLbl] = {pandoc.Str(language["title-block-affiliation-plural"])}
  	end
  	if meta[kAffiliationTitle] then
  	meta[kLabels][kAffiliationLbl] = meta[kAffiliationTitle]
  	end

A partial can do the same for a role heading with Pandoc's rest pipe.
$if(by-author/rest)$ is true only when the array holds more than one entry.

$if(by-author/rest)$$role-title-plural$$else$$role-title-single$$endif$

The example takes the two strings from plain metadata, which is how Quarto's own author-title and affiliation-title overrides work.
A custom key under language: is the better home, but it is discarded before templates see it in 1.11.
That is #14772, and #14773 corrects it.
With that correction the same partial reads $quarto.language.role-title-plural$, and a locale variation such as es: also works.

For reference about similar requests

Additions to the author schema are accepted.
degrees came from #6138 and group came from #6137, and both shipped in 1.4.
group is a good comparison for position.
It is a known affiliation field, and the default HTML title block still does not print it.

Requests to print more data in a default template stay open.
Issue #10410 asks for author roles in the default Typst template, and the reply there is that roles are already reachable from a partial through $it.role$.
That issue is in the "Future" milestone, together with #8476 for pronouns and #10749 for affiliations.

Two earlier discussions have the same answer as this one.

• What is the process to get YMAL author contribution information to actually show up in the rendered document? #9456
• How do I display custom front matter keywords in the title-block #12690

The full author schema is a data model for every format.
Each default template prints a small part of it, and the partial system covers the rest.

What could belong in Quarto

The default title block only has to be a sensible default.
A roles column is right for a translated book, and wrong for most other documents, so it is a good partial rather than a good default.

One part of this request is general, and it is small: a pair of title-block-role-single and title-block-role-plural keys in _language.yml, plus labels.roles next to labels.authors.
Then any partial gets a localised and plural role heading, and no default output changes.
This part is shared with #10410, because a Typst partial needs the same two strings.

One warning

Replace title-metadata.html, not title-block.html.
Quarto adds a header of its own when it cannot find header.quarto-title-block, and it moves the first title into it.
The HTML partials documentation points at src/resources/formats/html/pandoc, whose title-block.html is the Pandoc original and carries no class, which gives the two headers reported in #13841.
The partials that Quarto uses live in src/resources/formats/html/templates, as discussion #11434 also asks.

• quarto-cli/src/format/html/format-html-title.ts

  Lines 198 to 241 in abc6a78

  	const titleBlock = doc.querySelector("header.quarto-title-block");
  	const main = doc.querySelector("main");
  	// if no main element exists, this is likely a revealjs presentation
  	// which will generally have a title slide instead of a title block
  	// so we don't need to do anything
  	if (!titleBlock && main) {
  	const header = doc.createElement("header");
  	header.id = "title-block-header";
  	header.classList.add("quarto-title-block");
  	main.insertBefore(header, main.firstChild);
  	const h1s = Array.from(doc.querySelectorAll("h1"));
  	for (const h1n of h1s) {
  	const h1 = h1n as Element;
  	if (h1.classList.contains("quarto-secondary-nav-title")) {
  	continue;
  	}
  	// Now we need to check whether this is a plausible title element.
  	if (h1.parentElement?.tagName === "SECTION") {
  	// If the parent element is a section, then we need to check if there's
  	// any content before the section. If there is, then this is not a title
  	if (
  	h1.parentElement?.parentElement?.firstElementChild !==
  	h1.parentElement
  	) {
  	continue;
  	}
  	} else {
  	// If the parent element is not a section, then we need to check if there's
  	// any content before the h1. If there is, then this is not a title
  	if (h1.parentElement?.firstElementChild !== h1) {
  	continue;
  	}
  	}
  	const div = doc.createElement("div");
  	div.classList.add("quarto-title-banner");
  	h1.classList.add("title");
  	header.appendChild(h1);
  	break;
  	}
  	}

• quarto-cli/src/format/html/format-html-title.ts

  Lines 133 to 184 in abc6a78

  	export function documentTitlePartial(
  	format: Format,
  	) {
  	if (
  	format.metadata[kTitleBlockStyle] === false ||
  	format.metadata[kTitleBlockStyle] === "none"
  	) {
  	return {
  	partials: [],
  	templateParams: {},
  	};
  	} else {
  	const partials = [];
  	const templateParams: Metadata = {};
  	// Note whether we should be showing categories
  	templateParams[kTitleBlockCategories] =
  	format.metadata[kTitleBlockCategories] !== false ? "true" : "";
  	// Select the appropriate title block partial (banner vs no banner)
  	const banner = format.metadata[kTitleBlockBanner] as string | boolean;
  	const manuscriptTitle = format.metadata[kTitleBlockStyle] === "manuscript";
  	partials.push("_title-meta-author.html");
  	partials.push("title-metadata.html");
  	if (manuscriptTitle) {
  	partials.push("manuscript/title-block.html");
  	partials.push("manuscript/title-metadata.html");
  	} else if (banner) {
  	partials.push("banner/title-block.html");
  	} else {
  	partials.push("title-block.html");
  	}
  	// For banner partials, configure the options and pass them along in the metadata
  	if (banner || manuscriptTitle) {
  	// When the toc is on the left, be sure to add the special grid notation
  	const tocLeft = format.metadata[kTocLocation] === "left";
  	if (tocLeft) {
  	templateParams["banner-header-class"] = "toc-left";
  	}
  	}
  	return {
  	partials: partials.map((partial) => {
  	return formatResourcePath("html", join("templates", partial));
  	}),
  	templateParams,
  	};
  	}
  	}

[luifrancgom]

Thank you, Mickaël Canouil.

I really appreciate your help, the detailed explanation and your patience in showing me a much simpler solution.

[mcanouil]

I'm reopening as maintainers might decide differently or account for this while working on Quarto 2.