Fix website tool options silently ignored under the book key - #14881
Merged
Merged
Conversation
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.
Collaborator
✅ Snyk checks have passed. No issues have been found so far.
💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse. |
This was referenced Sep 11, 2026
Closed
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. |
cderv
added a commit
to quarto-dev/quarto-web
that referenced
this pull request
Sep 14, 2026
…nalytics anchor (#2186) * docs: relocate book-vs-website key note so it is reachable from the Analytics anchor The rule that book projects use `book:` instead of `website:` for these options was already documented, but the include lived under Social Metadata while Analytics sits roughly 150 lines further down. A reader landing directly on the Analytics anchor never saw it. Move the note to a page-level intro so the generalizing sentence actually applies page-wide as written, and add a short pointer inside Analytics for readers who land there via a deep link. Also add `plausible-analytics` to the book-vs-website example so it concretely covers the reported case. Companion to quarto-dev/quarto-cli#14881, which fixes the underlying config bug reported in quarto-dev/quarto-cli#14879. * Update docs/books/_book-vs-website-key.qmd * Update docs/books/_book-vs-website-key.qmd
cderv
added a commit
that referenced
this pull request
Sep 15, 2026
Adds Playwright fixture and spec to verify the back-to-top navigation control works correctly in book projects. This complements #14881's fix to book projects silently dropping website-level tool options, verifying the control not only injects into the HTML but behaves correctly in the browser. - Playwright fixture with book project fixture and interactions - Spec asserting scroll show/hide behavior and click-to-top reset - Documentation of scroll-state race pattern for Playwright best practices, addressing flakiness in scroll event timing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
HTML books are websites, and the documented contract is that website tools go under the
bookkey in a book project rather than underwebsite, 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), plusback-to-top-navigationandimage-alt, which had no issue filed.Root cause
bookProjectConfiginsrc/project/types/book/book-config.tsimplements that contract by copying a hand-maintained list of website keys frombookinto the internal website config. Keys added tobase-websitein the schema after that list was written were never added to it, so they passed validation and were then dropped with no warning.google-analyticsis on the list, which is why it works in a book whileplausible-analyticsdid 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-txtfailure toformatExtrasnot being inherited by books:src/project/types/book/book.tsdoes callwebsiteProjectType.formatExtras, and the llms.txt index generates correctly once the key is copied.draftsanddraft-modeare 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
websitekeySetting one of these five under a top-level
websitekey in a book project happened to work before, because a key absent from the copy list was left untouched. They are now read frombooklike 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-txtwebsite tests render withoutput-dir: .and did not ignore thesearch.jsonandsite_libs/they produce, so any run of the website suite left untracked files behind.Closes #10114, closes #14276, closes #14879