I have:
Bug description
Bug description
Context
I’m trying to host multiple independent Quarto books under the same domain, for example:
/book/EST0033//book/TAS0000/- etc.
and I want all of them to share one single, centralized Quarto assets directory, for example:
The goal is to avoid duplicating the same Quarto JS/CSS/theme resources for every book, improving maintenance and browser caching.
Hosting setup
- Hosting provider: GitHub Pages
- Domain: Custom domain (root is
/): https://estatistica.cesargabriel.com.br/
- Because it’s a custom domain, using absolute paths like
/book/... is fine (the issue is not the repo subpath prefix that exists on *.github.io/<repo>/...).
Current workflow (workaround)
- I write and render everything under
books/.
- On deploy, the rendered output is copied from
books/book/ to public/book/.
- I run a custom post-processing script/package (Python) that rewrites the
<head> of every rendered HTML file to:
- consolidate assets into
/book/assets/
- rewrite relative asset links to absolute ones
- preserve
<meta name="quarto:offset" ...> because Quarto JS (navigation/search/etc.) depends on it.
This workaround works, but it is fragile and hard to maintain as Quarto evolves.
The problem
Quarto currently generates each book as a fully self-contained site (with its own assets/ and relative links based on directory depth). When multiple books are deployed side-by-side and assets are centralized, pages start to break unless we rewrite HTML afterwards.
Even with a custom domain and absolute asset paths, the Quarto runtime relies on page-relative assumptions (including quarto:offset) for navigation/search and related behavior, which makes the “shared assets across multiple books” pattern difficult without external tooling.
Steps to reproduce
- Render 2+ Quarto books (
project: book), each in its own output folder.
- Deploy them to a single site under:
/book/<BOOKNAME>/ for each book- one shared
/book/assets/ directory for all of them
- Serve from a custom domain root (
/).
- Without post-processing the generated HTML, assets and/or Quarto JS behavior (navigation/search/etc.) break because the generated HTML expects per-book relative
assets/ and relies on directory depth + quarto:offset.
Actual behavior
- Asset references break when
assets/ is centralized (unless the HTML is rewritten).
- Some runtime behaviors (search/navigation or other JS features that use offsets) depend on assumptions that are hard to satisfy in a multi-book + shared-assets layout.
- A custom “HTML head rewriter” is required to make it work reliably.
Expected behavior
Provide a supported and documented way to deploy multiple books under the same domain while sharing a single assets directory, without any post-processing hacks. For example:
- A configuration option such as
assets-base-path (global or per project) so Quarto can generate asset references pointing to a shared location (e.g. /book/assets/).
- Or an official “multi-book deployment” mode that ensures:
- assets can be shared across books
- navigation/search and other Quarto JS features remain correct
- output HTML is correct without requiring external rewriting scripts
This multi-book + shared-assets pattern is increasingly common for portals, schools, course websites, and larger scientific sites, so first-class support would be very valuable.
Your environment
- IDE: terminal + any editor (VSCode/RStudio)
- OS: Windows 11 Home Single Language (Version 25H2) / also reproduced in deployment environment
- Quarto CLI: latest stable
Quarto check output
I have:
Bug description
Bug description
Context
I’m trying to host multiple independent Quarto books under the same domain, for example:
/book/EST0033//book/TAS0000/and I want all of them to share one single, centralized Quarto assets directory, for example:
/book/assets/The goal is to avoid duplicating the same Quarto JS/CSS/theme resources for every book, improving maintenance and browser caching.
Hosting setup
/): https://estatistica.cesargabriel.com.br//book/...is fine (the issue is not the repo subpath prefix that exists on*.github.io/<repo>/...).Current workflow (workaround)
books/.books/book/topublic/book/.<head>of every rendered HTML file to:/book/assets/<meta name="quarto:offset" ...>because Quarto JS (navigation/search/etc.) depends on it.This workaround works, but it is fragile and hard to maintain as Quarto evolves.
The problem
Quarto currently generates each book as a fully self-contained site (with its own
assets/and relative links based on directory depth). When multiple books are deployed side-by-side and assets are centralized, pages start to break unless we rewrite HTML afterwards.Even with a custom domain and absolute asset paths, the Quarto runtime relies on page-relative assumptions (including
quarto:offset) for navigation/search and related behavior, which makes the “shared assets across multiple books” pattern difficult without external tooling.Steps to reproduce
project: book), each in its own output folder./book/<BOOKNAME>/for each book/book/assets/directory for all of them/).assets/and relies on directory depth +quarto:offset.Actual behavior
assets/is centralized (unless the HTML is rewritten).Expected behavior
Provide a supported and documented way to deploy multiple books under the same domain while sharing a single assets directory, without any post-processing hacks. For example:
assets-base-path(global or per project) so Quarto can generate asset references pointing to a shared location (e.g./book/assets/).This multi-book + shared-assets pattern is increasingly common for portals, schools, course websites, and larger scientific sites, so first-class support would be very valuable.
Your environment
Quarto check output