Fix false citeproc warning from @ in book metadata URLs (#14105)

When a book project has URLs containing `@` in navbar config (e.g.,
`href: https://mastodon.online/@user`) and a bibliography, Pandoc emits
false `[WARNING] Citeproc: citation not found` warnings because it
parses YAML metadata strings as Markdown, interpreting `@user` as a
citation reference.

Book metadata can't be deleted before passing to Pandoc (unlike website
metadata) because `{{< meta book.* >}}` shortcodes depend on it.

Escape `@` to `&#64;` in URL strings within `book` metadata before
writing the Pandoc metadata file. The escaping is scoped to URL strings
only (via `isExternalPath()`), so non-URL metadata strings like
intentional citations in description fields are left untouched. Pandoc
resolves the HTML entity back to `@` in the AST, so templates and
shortcodes see the original character.

Fixes #12136

Author: cderv

news/changelog-1.9.md

@@ -131,6 +131,7 @@ All changes included in 1.9:
 
 ### `book`
 
+- ([#12136](https://github.com/quarto-dev/quarto-cli/issues/12136)): Fix false `citeproc: citation not found` warnings when book metadata URLs contain `@` (e.g., Mastodon links). The `@` in URL strings is now escaped before passing to Pandoc, preventing misinterpretation as citation references.
 - ([#13769](https://github.com/quarto-dev/quarto-cli/issues/13769)): Apply `repo-link-target` and `repo-link-rel` options to tools in book sidebar for consistent link attribute handling with website projects. (author: @mcanouil)
 
 ### `manuscript`

src/command/render/pandoc.ts

@@ -27,6 +27,7 @@ import { Document } from "../../core/deno-dom.ts";
 import { execProcess } from "../../core/process.ts";
 import { dirAndStem, normalizePath } from "../../core/path.ts";
 import { mergeConfigs } from "../../core/config.ts";
+import { isExternalPath } from "../../core/url.ts";
 
 import {
   Format,
@@ -1339,6 +1340,13 @@ export async function runPandoc(
     }
   }
 
+  // Escape @ in book metadata to prevent false citeproc warnings (#12136).
+  // Book metadata can't be deleted like website/about because {{< meta book.* >}}
+  // shortcodes depend on it. Pandoc resolves &#64; back to @ in the AST.
+  if (pandocPassedMetadata.book) {
+    pandocPassedMetadata.book = escapeAtInMetadata(pandocPassedMetadata.book);
+  }
+
   Deno.writeTextFileSync(
     metadataTemp,
     stringify(pandocPassedMetadata, {
@@ -1833,3 +1841,21 @@ function resolveTextHighlightStyle(
   }
   return extras;
 }
+
+// deno-lint-ignore no-explicit-any
+function escapeAtInMetadata(value: any): any {
+  if (typeof value === "string") {
+    return isExternalPath(value) ? value.replaceAll("@", "&#64;") : value;
+  }
+  if (Array.isArray(value)) {
+    return value.map(escapeAtInMetadata);
+  }
+  if (value !== null && typeof value === "object") {
+    const result: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value)) {
+      result[k] = escapeAtInMetadata(v);
+    }
+    return result;
+  }
+  return value;
+}

tests/docs/smoke-all/2026/02/24/issue-12136/.gitignore

@@ -0,0 +1,2 @@
+/.quarto/
+**/*.quarto_ipynb

tests/docs/smoke-all/2026/02/24/issue-12136/_quarto.yml

@@ -0,0 +1,16 @@
+project:
+  type: book
+
+book:
+  title: "Test Issue 12136"
+  navbar:
+    right:
+      - icon: mastodon
+        href: https://mastodon.online/@testuser
+  chapters:
+    - index.qmd
+
+bibliography: references.bib
+
+format:
+  html: default

tests/docs/smoke-all/2026/02/24/issue-12136/index.qmd

@@ -0,0 +1,17 @@
+---
+title: "Test"
+_quarto:
+  tests:
+    html:
+      printsMessage:
+        level: INFO
+        regex: 'Citeproc: citation'
+        negate: true
+      ensureHtmlElements:
+        - ['a.nav-link[href="https://mastodon.online/@testuser"]']
+        - []
+---
+
+# Test {.unnumbered}
+
+No false citeproc warnings from @ in book navbar URLs.

tests/docs/smoke-all/2026/02/24/issue-12136/references.bib

@@ -0,0 +1,5 @@
+@misc{example,
+  author = {Test Author},
+  title = {Example},
+  year = {2024}
+}

tests/docs/smoke-all/book/htmlbook/.gitignore

@@ -1 +1,3 @@
 /.quarto/
+
+**/*.quarto_ipynb

tests/docs/smoke-all/book/page-footer/.gitignore

@@ -1,2 +1,3 @@
 /.quarto/
-/_book/
+/_book/
+**/*.quarto_ipynb

tests/docs/smoke-all/book/simple/.gitignore

@@ -1 +1,3 @@
 /.quarto/
+
+**/*.quarto_ipynb