Skip to content

Fix website tool options silently ignored under the book key - #14881

Open
cderv wants to merge 2 commits into
mainfrom
fix/issue-14879
Open

Fix website tool options silently ignored under the book key#14881
cderv wants to merge 2 commits into
mainfrom
fix/issue-14879

Conversation

@cderv

@cderv cderv commented Sep 11, 2026

Copy link
Copy Markdown
Member

HTML books are websites, and the documented contract is that website tools go under the book key in a book project rather than under website, as stated in https://quarto.org/docs/books/book-output.html#website-tools. Five options that the book schema accepts did nothing there: plausible-analytics (#14879), llms-txt (#14276), announcement (#10114), plus back-to-top-navigation and image-alt, which had no issue filed.

Root cause

bookProjectConfig in src/project/types/book/book-config.ts implements that contract by copying a hand-maintained list of website keys from book into the internal website config. Keys added to base-website in the schema after that list was written were never added to it, so they passed validation and were then dropped with no warning. google-analytics is on the list, which is why it works in a book while plausible-analytics did not.

Nothing beyond the copy was missing. Each of the five works as soon as the value reaches the website config, so the hooks that consume them are already reachable from a book render. That is worth noting for #14276, whose description attributes the llms-txt failure to formatExtras not being inherited by books: src/project/types/book/book.ts does call websiteProjectType.formatExtras, and the llms.txt index generates correctly once the key is copied.

drafts and draft-mode are absent from the list too and are left alone here. They filter which files a project renders rather than adding an HTML tool, and #9233 tracks them as a feature request.

Note on the top-level website key

Setting one of these five under a top-level website key in a book project happened to work before, because a key absent from the copy list was left untouched. They are now read from book like every other website tool in a book, so that form no longer applies.

A companion quarto-web PR moves the book-versus-website key note so it is visible from the analytics section of the website tools page, where it was previously 150 lines above.

The second commit is unrelated test hygiene: two llms-txt website tests render with output-dir: . and did not ignore the search.json and site_libs/ they produce, so any run of the website suite left untracked files behind.

Closes #10114, closes #14276, closes #14879

HTML books are websites, and the documented contract is that website tools
go under the `book` key in a book project rather than under `website`. The
book project type implements this by copying a hand-maintained list of
website keys from `book` into the internal website config. Keys added to the
website schema after that list was written were never added to it, so those
options validated against the book schema and then silently did nothing, with
no warning.

This adds the five keys that had drifted out of sync: `plausible-analytics`,
`llms-txt`, `announcement`, `back-to-top-navigation`, and `image-alt`.

Setting these under a top-level `website` key in a book project happened to
work before, because a key absent from the copy list was left untouched. Now
that they are on the list they follow the same rule as every other website
tool in a book and are read from `book`, so that incidental form no longer
applies.

Closes #10114
Closes #14276
Closes #14879
Both tests render with `output-dir: .`, so search.json and site_libs/ land in
the source directory and show up as untracked files after any run of the
website suite. Their sibling llms-txt-shortcode already ignores both; these
two were copied from an earlier version of that list.

search.json is spelled out rather than globbed as *.json because
llms-txt-listing has a tracked listings.json fixture.
@posit-snyk-bot

posit-snyk-bot commented Sep 11, 2026

Copy link
Copy Markdown
Collaborator

Snyk checks have passed. No issues have been found so far.

Status Scan Engine Critical High Medium Low Total (0)
Open Source Security 0 0 0 0 0 issues
Licenses 0 0 0 0 0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

@cderv

cderv commented Sep 11, 2026

Copy link
Copy Markdown
Member Author

Docs companion: quarto-dev/quarto-web#2186. The book-vs-website key note already existed, it just sat under Social Metadata while Analytics is well below it, so a reader landing on the Analytics anchor never saw it. Moved to a page-level intro and added a short pointer inside Analytics.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

2 participants