From db48d34fb365256db5089f346855b1e8e41f5c97 Mon Sep 17 00:00:00 2001 From: Christophe Dervieux Date: Tue, 20 Oct 2026 15:00:30 +0200 Subject: [PATCH 1/4] Only write the default listing metadata link when it has visible text The default listing template always wrapped the metadata block in a link to the post. When the block shows nothing (no date or author, fields that exclude every metadata field, or a listed custom field that is missing or empty on the post), the link is empty: a Tab stop with no accessible name, flagged by axe `link-name`. The link is now written only when the block has visible text. The guard follows the same field checks as the children it wraps, plus truthiness for extra fields, whose empty values render a bare ` `. The `.metadata` div stays on every item. In the row layout it is a flex item, so removing it on items without metadata would widen `.body` on those items only and make body widths differ within one listing. --- .../website/listing/item-default.ejs.md | 25 ++++++- tests/docs/listings-metadata-link/.gitignore | 4 ++ tests/docs/listings-metadata-link/_quarto.yml | 5 ++ .../listings-metadata-link/custom-field.qmd | 10 +++ tests/docs/listings-metadata-link/fields.qmd | 10 +++ tests/docs/listings-metadata-link/index.qmd | 10 +++ .../posts/dated/index.qmd | 8 +++ .../posts/empty-version/index.qmd | 6 ++ .../posts/undated/index.qmd | 5 ++ .../listings-metadata-link/reading-time.qmd | 10 +++ .../site/render-listing-metadata-link.test.ts | 72 +++++++++++++++++++ 11 files changed, 162 insertions(+), 3 deletions(-) create mode 100644 tests/docs/listings-metadata-link/.gitignore create mode 100644 tests/docs/listings-metadata-link/_quarto.yml create mode 100644 tests/docs/listings-metadata-link/custom-field.qmd create mode 100644 tests/docs/listings-metadata-link/fields.qmd create mode 100644 tests/docs/listings-metadata-link/index.qmd create mode 100644 tests/docs/listings-metadata-link/posts/dated/index.qmd create mode 100644 tests/docs/listings-metadata-link/posts/empty-version/index.qmd create mode 100644 tests/docs/listings-metadata-link/posts/undated/index.qmd create mode 100644 tests/docs/listings-metadata-link/reading-time.qmd create mode 100644 tests/smoke/site/render-listing-metadata-link.test.ts diff --git a/src/resources/projects/website/listing/item-default.ejs.md b/src/resources/projects/website/listing/item-default.ejs.md index 823f32c18d3..fbf6e912361 100644 --- a/src/resources/projects/website/listing/item-default.ejs.md +++ b/src/resources/projects/website/listing/item-default.ejs.md @@ -14,9 +14,7 @@ return !["title", "image", "image-alt", "date", "author", "subtitle", "descripti // Capture the item number for utility functions that need it const itemNumber = listing.utilities.itemNumber(); -// Writes a metadata value -const outputMetadata = (item, field) => { - +// Reads a (possibly dotted) metadata field from an item const readField = (item, field) => { let value = item[field]; if (field.includes(".") && !field.endsWith(".") && !field.startsWith(".")) { @@ -29,6 +27,19 @@ value = value[deref]; return value; } +// Whether the metadata block shows any text for the item +const hasMetadata = (item) => { +return Boolean( +(fields.includes('date') && item.date) || +(fields.includes('author') && item.author) || +(fields.includes('reading-time') && item['reading-time']) || +otherFields.some(field => readField(item, field)) +); +} + +// Writes a metadata value +const outputMetadata = (item, field) => { + let value = readField(item, field); if (value !== undefined) { print(`
${listing.utilities.outputLink(item, field, value)}
`); @@ -91,10 +102,14 @@ print(`
${listing.utilities.outputLi ::: {.metadata} +<% if (hasMetadata(item)) { %> + ```{=html} ``` +<% } %> + <% if (fields.includes('date') && item.date) { %>
<%= item.date %>
<% } %> @@ -115,10 +130,14 @@ print(`
${listing.utilities.outputLi <% outputMetadata(item, field) %> <% } %> +<% if (hasMetadata(item)) { %> + ```{=html} ``` +<% } %> + ::: ::: diff --git a/tests/docs/listings-metadata-link/.gitignore b/tests/docs/listings-metadata-link/.gitignore new file mode 100644 index 00000000000..812977e5f74 --- /dev/null +++ b/tests/docs/listings-metadata-link/.gitignore @@ -0,0 +1,4 @@ +/.quarto/ +_site/ + +**/*.quarto_ipynb diff --git a/tests/docs/listings-metadata-link/_quarto.yml b/tests/docs/listings-metadata-link/_quarto.yml new file mode 100644 index 00000000000..1550450644e --- /dev/null +++ b/tests/docs/listings-metadata-link/_quarto.yml @@ -0,0 +1,5 @@ +project: + type: website + +website: + title: "Listing metadata link" diff --git a/tests/docs/listings-metadata-link/custom-field.qmd b/tests/docs/listings-metadata-link/custom-field.qmd new file mode 100644 index 00000000000..df11e65f15b --- /dev/null +++ b/tests/docs/listings-metadata-link/custom-field.qmd @@ -0,0 +1,10 @@ +--- +title: "Posts with a custom field" +listing: + contents: posts + type: default + sort: "title" + fields: [title, version] +--- + +A default listing with a custom metadata field. diff --git a/tests/docs/listings-metadata-link/fields.qmd b/tests/docs/listings-metadata-link/fields.qmd new file mode 100644 index 00000000000..d771e75b662 --- /dev/null +++ b/tests/docs/listings-metadata-link/fields.qmd @@ -0,0 +1,10 @@ +--- +title: "Posts without metadata fields" +listing: + contents: posts + type: default + sort: "title" + fields: [image, title] +--- + +A default listing whose fields exclude every metadata field. diff --git a/tests/docs/listings-metadata-link/index.qmd b/tests/docs/listings-metadata-link/index.qmd new file mode 100644 index 00000000000..3c6e2b2299f --- /dev/null +++ b/tests/docs/listings-metadata-link/index.qmd @@ -0,0 +1,10 @@ +--- +title: "Posts" +listing: + contents: posts + type: default + sort: "title" +--- + +A default listing with the default fields. The post without a date or +an author has nothing to show in its metadata block. diff --git a/tests/docs/listings-metadata-link/posts/dated/index.qmd b/tests/docs/listings-metadata-link/posts/dated/index.qmd new file mode 100644 index 00000000000..4988bd0b611 --- /dev/null +++ b/tests/docs/listings-metadata-link/posts/dated/index.qmd @@ -0,0 +1,8 @@ +--- +title: "Post with a date and an author" +date: 2026-01-01 +author: "Jane Doe" +version: "1.0" +--- + +Text. diff --git a/tests/docs/listings-metadata-link/posts/empty-version/index.qmd b/tests/docs/listings-metadata-link/posts/empty-version/index.qmd new file mode 100644 index 00000000000..ce0c46c6eab --- /dev/null +++ b/tests/docs/listings-metadata-link/posts/empty-version/index.qmd @@ -0,0 +1,6 @@ +--- +title: "Post with an empty version" +version: "" +--- + +Text. diff --git a/tests/docs/listings-metadata-link/posts/undated/index.qmd b/tests/docs/listings-metadata-link/posts/undated/index.qmd new file mode 100644 index 00000000000..7043b77865b --- /dev/null +++ b/tests/docs/listings-metadata-link/posts/undated/index.qmd @@ -0,0 +1,5 @@ +--- +title: "Post without a date or an author" +--- + +Text. diff --git a/tests/docs/listings-metadata-link/reading-time.qmd b/tests/docs/listings-metadata-link/reading-time.qmd new file mode 100644 index 00000000000..0e0518b4a14 --- /dev/null +++ b/tests/docs/listings-metadata-link/reading-time.qmd @@ -0,0 +1,10 @@ +--- +title: "Posts with reading time" +listing: + contents: posts + type: default + sort: "title" + fields: [title, reading-time] +--- + +A default listing whose only metadata field is the reading time. diff --git a/tests/smoke/site/render-listing-metadata-link.test.ts b/tests/smoke/site/render-listing-metadata-link.test.ts new file mode 100644 index 00000000000..b4b5702237d --- /dev/null +++ b/tests/smoke/site/render-listing-metadata-link.test.ts @@ -0,0 +1,72 @@ +/* + * render-listing-metadata-link.test.ts + * + * Copyright (C) 2026 Posit Software, PBC + */ +import { join } from "../../../src/deno_ral/path.ts"; +import { removeIfExists } from "../../../src/core/path.ts"; +import { testQuartoCmd } from "../../test.ts"; +import { docs } from "../../utils.ts"; +import { + ensureHtmlElementCount, + ensureHtmlElements, + noErrorsOrWarnings, +} from "../../verify.ts"; + +// The default listing template wraps the metadata block of every post in a +// link to the post. When nothing in that block shows text, the link is empty: +// a tab stop with no accessible name. The link is only written when the +// block has visible content. Cases covered: no date or author, fields that +// exclude every metadata field, a listed custom field that is missing or +// empty on the post. Every post keeps its metadata column to preserve the +// row layout. +const projectDir = docs("listings-metadata-link"); +const outputDir = join(projectDir, "_site"); +const metadataColumn = "div.quarto-post > div.metadata"; + +testQuartoCmd("render", [projectDir], [ + noErrorsOrWarnings, + ...["index", "fields", "reading-time", "custom-field"].map((page) => + ensureHtmlElementCount(join(outputDir, `${page}.html`), { + selectors: metadataColumn, + counts: 3, + }) + ), + // default fields + ensureHtmlElements(join(outputDir, "index.html"), [ + 'div.metadata a[href$="/dated/index.html"] div.listing-date', + 'div.metadata a[href$="/dated/index.html"] div.listing-author', + ], [ + 'div.metadata a[href$="/undated/index.html"]', + 'div.metadata a[href$="/empty-version/index.html"]', + ]), + // fields exclude every metadata field + ensureHtmlElements(join(outputDir, "fields.html"), [], [ + "div.metadata a", + ]), + // every post has a reading time, so every post keeps its link + ensureHtmlElements(join(outputDir, "reading-time.html"), [ + 'div.metadata a[href$="/dated/index.html"] div.listing-reading-time', + 'div.metadata a[href$="/undated/index.html"] div.listing-reading-time', + 'div.metadata a[href$="/empty-version/index.html"] div.listing-reading-time', + ], []), + // the link is only written where version has a value + ensureHtmlElements(join(outputDir, "custom-field.html"), [ + 'div.metadata a[href$="/dated/index.html"] div.listing-version', + ], [ + 'div.metadata a[href$="/undated/index.html"]', + 'div.metadata a[href$="/empty-version/index.html"]', + ]), + // dated and empty-version both keep their listing-version div + ensureHtmlElementCount(join(outputDir, "custom-field.html"), { + selectors: "div.metadata div.listing-version", + counts: 2, + }), +], { + name: "Listing metadata link is only written when it has content", + teardown: () => { + removeIfExists(outputDir); + removeIfExists(join(projectDir, ".quarto")); + return Promise.resolve(); + }, +}); From 376624cc7a48393b9b4f800d6f5b10eddfa04304 Mon Sep 17 00:00:00 2001 From: Christophe Dervieux Date: Tue, 20 Oct 2026 15:10:39 +0200 Subject: [PATCH 2/4] Treat empty lists and blank strings as no metadata text The guard tested truthiness, but a custom field holding an empty list or a whitespace-only string is truthy and still renders no visible text, so the metadata link stayed empty for those posts. The same holds for `author`, which listing items carry as a list. The guard now asks whether each value renders as visible text: falsy values fall back to a bare ` `, and empty lists and blank strings stringify to whitespace. The children are unchanged. --- .../projects/website/listing/item-default.ejs.md | 14 ++++++++------ .../posts/blank-version/index.qmd | 6 ++++++ .../posts/empty-list-version/index.qmd | 6 ++++++ .../site/render-listing-metadata-link.test.ts | 14 +++++++++----- 4 files changed, 29 insertions(+), 11 deletions(-) create mode 100644 tests/docs/listings-metadata-link/posts/blank-version/index.qmd create mode 100644 tests/docs/listings-metadata-link/posts/empty-list-version/index.qmd diff --git a/src/resources/projects/website/listing/item-default.ejs.md b/src/resources/projects/website/listing/item-default.ejs.md index fbf6e912361..41cf1126dee 100644 --- a/src/resources/projects/website/listing/item-default.ejs.md +++ b/src/resources/projects/website/listing/item-default.ejs.md @@ -27,14 +27,16 @@ value = value[deref]; return value; } +// Whether a value renders as visible text (falsy values render as  , +// empty lists and blank strings as whitespace) +const hasText = (value) => !!value && String(value).trim() !== ""; + // Whether the metadata block shows any text for the item const hasMetadata = (item) => { -return Boolean( -(fields.includes('date') && item.date) || -(fields.includes('author') && item.author) || -(fields.includes('reading-time') && item['reading-time']) || -otherFields.some(field => readField(item, field)) -); +return (fields.includes('date') && hasText(item.date)) || +(fields.includes('author') && hasText(item.author)) || +(fields.includes('reading-time') && hasText(item['reading-time'])) || +otherFields.some(field => hasText(readField(item, field))); } // Writes a metadata value diff --git a/tests/docs/listings-metadata-link/posts/blank-version/index.qmd b/tests/docs/listings-metadata-link/posts/blank-version/index.qmd new file mode 100644 index 00000000000..972820baa02 --- /dev/null +++ b/tests/docs/listings-metadata-link/posts/blank-version/index.qmd @@ -0,0 +1,6 @@ +--- +title: "Post with a blank version" +version: " " +--- + +Text. diff --git a/tests/docs/listings-metadata-link/posts/empty-list-version/index.qmd b/tests/docs/listings-metadata-link/posts/empty-list-version/index.qmd new file mode 100644 index 00000000000..b33cf3fcb89 --- /dev/null +++ b/tests/docs/listings-metadata-link/posts/empty-list-version/index.qmd @@ -0,0 +1,6 @@ +--- +title: "Post with an empty version list" +version: [] +--- + +Text. diff --git a/tests/smoke/site/render-listing-metadata-link.test.ts b/tests/smoke/site/render-listing-metadata-link.test.ts index b4b5702237d..f3953f73427 100644 --- a/tests/smoke/site/render-listing-metadata-link.test.ts +++ b/tests/smoke/site/render-listing-metadata-link.test.ts @@ -17,8 +17,8 @@ import { // link to the post. When nothing in that block shows text, the link is empty: // a tab stop with no accessible name. The link is only written when the // block has visible content. Cases covered: no date or author, fields that -// exclude every metadata field, a listed custom field that is missing or -// empty on the post. Every post keeps its metadata column to preserve the +// exclude every metadata field, a listed custom field that is missing, empty, +// blank or an empty list on the post. Every post keeps its metadata column to preserve the // row layout. const projectDir = docs("listings-metadata-link"); const outputDir = join(projectDir, "_site"); @@ -29,7 +29,7 @@ testQuartoCmd("render", [projectDir], [ ...["index", "fields", "reading-time", "custom-field"].map((page) => ensureHtmlElementCount(join(outputDir, `${page}.html`), { selectors: metadataColumn, - counts: 3, + counts: 5, }) ), // default fields @@ -49,6 +49,8 @@ testQuartoCmd("render", [projectDir], [ 'div.metadata a[href$="/dated/index.html"] div.listing-reading-time', 'div.metadata a[href$="/undated/index.html"] div.listing-reading-time', 'div.metadata a[href$="/empty-version/index.html"] div.listing-reading-time', + 'div.metadata a[href$="/blank-version/index.html"] div.listing-reading-time', + 'div.metadata a[href$="/empty-list-version/index.html"] div.listing-reading-time', ], []), // the link is only written where version has a value ensureHtmlElements(join(outputDir, "custom-field.html"), [ @@ -56,11 +58,13 @@ testQuartoCmd("render", [projectDir], [ ], [ 'div.metadata a[href$="/undated/index.html"]', 'div.metadata a[href$="/empty-version/index.html"]', + 'div.metadata a[href$="/blank-version/index.html"]', + 'div.metadata a[href$="/empty-list-version/index.html"]', ]), - // dated and empty-version both keep their listing-version div + // every post but undated keeps its listing-version div ensureHtmlElementCount(join(outputDir, "custom-field.html"), { selectors: "div.metadata div.listing-version", - counts: 2, + counts: 4, }), ], { name: "Listing metadata link is only written when it has content", From 442810b5f6e98f670f33a1f54040093875080165 Mon Sep 17 00:00:00 2001 From: Christophe Dervieux Date: Tue, 20 Oct 2026 15:27:24 +0200 Subject: [PATCH 3/4] Only write the default listing subtitle link for a post with a subtitle The subtitle line was written whenever `subtitle` is in the listing fields, which it is by default, so every post without a subtitle got an empty link in its body: a Tab stop with no accessible name, flagged by axe `link-name`. It now uses the same visible-text check as the metadata link. Unlike the metadata column, the subtitle line has no layout role, so it is dropped entirely. Fixes #14380 --- .../projects/website/listing/item-default.ejs.md | 2 +- .../listings-metadata-link/posts/dated/index.qmd | 1 + .../smoke/site/render-listing-metadata-link.test.ts | 13 +++++++++++-- 3 files changed, 13 insertions(+), 3 deletions(-) diff --git a/src/resources/projects/website/listing/item-default.ejs.md b/src/resources/projects/website/listing/item-default.ejs.md index 41cf1126dee..0f2f9e0896c 100644 --- a/src/resources/projects/website/listing/item-default.ejs.md +++ b/src/resources/projects/website/listing/item-default.ejs.md @@ -69,7 +69,7 @@ print(`
${listing.utilities.outputLi <% if (fields.includes('title')) { %>

<%= item.title %>

-<% if (fields.includes('subtitle')) { %> +<% if (fields.includes('subtitle') && hasText(item.subtitle)) { %>
<%= item.subtitle %>
<% } %> <% } %> diff --git a/tests/docs/listings-metadata-link/posts/dated/index.qmd b/tests/docs/listings-metadata-link/posts/dated/index.qmd index 4988bd0b611..1de7395f430 100644 --- a/tests/docs/listings-metadata-link/posts/dated/index.qmd +++ b/tests/docs/listings-metadata-link/posts/dated/index.qmd @@ -2,6 +2,7 @@ title: "Post with a date and an author" date: 2026-01-01 author: "Jane Doe" +subtitle: "A subtitle" version: "1.0" --- diff --git a/tests/smoke/site/render-listing-metadata-link.test.ts b/tests/smoke/site/render-listing-metadata-link.test.ts index f3953f73427..b72411e66bb 100644 --- a/tests/smoke/site/render-listing-metadata-link.test.ts +++ b/tests/smoke/site/render-listing-metadata-link.test.ts @@ -18,8 +18,9 @@ import { // a tab stop with no accessible name. The link is only written when the // block has visible content. Cases covered: no date or author, fields that // exclude every metadata field, a listed custom field that is missing, empty, -// blank or an empty list on the post. Every post keeps its metadata column to preserve the -// row layout. +// blank or an empty list on the post. Every post keeps its metadata column to +// preserve the row layout. The subtitle link is likewise only written for a +// post with a subtitle. const projectDir = docs("listings-metadata-link"); const outputDir = join(projectDir, "_site"); const metadataColumn = "div.quarto-post > div.metadata"; @@ -40,6 +41,14 @@ testQuartoCmd("render", [projectDir], [ 'div.metadata a[href$="/undated/index.html"]', 'div.metadata a[href$="/empty-version/index.html"]', ]), + // only the post with a subtitle gets a subtitle link (#14380) + ensureHtmlElementCount(join(outputDir, "index.html"), { + selectors: [ + 'div.listing-subtitle a[href$="/dated/index.html"]', + "div.listing-subtitle", + ], + counts: [1, 1], + }), // fields exclude every metadata field ensureHtmlElements(join(outputDir, "fields.html"), [], [ "div.metadata a", From 2db1cece0fd78bebaf8fdbbbb86850c3491c8e69 Mon Sep 17 00:00:00 2001 From: Christophe Dervieux Date: Tue, 20 Oct 2026 15:27:48 +0200 Subject: [PATCH 4/4] Add changelog entries for empty default listing links (#14380, #15129) --- news/changelog-1.11.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/news/changelog-1.11.md b/news/changelog-1.11.md index 7b15564dd06..d79f83edf04 100644 --- a/news/changelog-1.11.md +++ b/news/changelog-1.11.md @@ -28,6 +28,7 @@ All changes included in 1.11: - ([#14376](https://github.com/quarto-dev/quarto-cli/issues/14376)): Translate the new `navigation-*-label` keys in all 33 built-in language files. The values are drawn from existing human-translated interface strings (LibreOffice, GNOME, Wikidata) and each one carries a comment naming its source; values that were adapted rather than used verbatim are marked `needs review`. - ([#14376](https://github.com/quarto-dev/quarto-cli/issues/14376)): Label the table of contents `