Problems sharing assets among multiple Quarto books on custom domain (multi-book, one-assets) #14438

czargab18 · 2026-04-25T18:14:50Z

czargab18
Apr 25, 2026

I have:

searched the issue tracker for similar issues
installed the latest version of Quarto CLI
formatted my issue following the Bug Reports guide

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:

/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

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

PS C:\Users\cesar.castro\github\estatistica> quarto --version
>> quarto check
>> quarto check installations
>> quarto check knitr
>> quarto check jupyter
1.9.37
Quarto 1.9.37
[>] Checking environment information...
      Quarto cache location: C:\Users\cesar.castro\AppData\Local\quarto
[>] Checking versions of quarto binary dependencies...
      Pandoc version 3.8.3: OK
      Dart Sass version 1.87.0: OK
      Deno version 2.4.5: OK
      Typst version 0.14.2: OK
[>] Checking versions of quarto dependencies......OK
[>] Checking Quarto installation......OK
      Version: 1.9.37
      Path: C:\Users\cesar.castro\AppData\Local\Programs\Quarto\bin
      CodePage: 1252

[>] Checking tools....................OK
      TinyTeX: (not installed)
      Chromium: (not installed)
      Chrome Headless Shell: (not installed)
      VeraPDF: (not installed)

[>] Checking LaTeX....................OK
      Tex:  (not detected)

[>] Checking Chrome Headless....................OK
      Using: Chrome found on system
      Path: C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe
      Source: Windows Registry

[>] Checking basic markdown render....OK

[>] Checking R installation...........OK
      Version: 4.5.3
      Path: C:/Users/cesar.castro/AppData/Local/Programs/R/R-4.5.3
      LibPaths:
        - C:/Users/cesar.castro/AppData/Local/Programs/R/R-4.5.3/library
      knitr: (None)
      rmarkdown: (None)

      The knitr package is not available in this R installation.
      Install with install.packages("knitr")
      The rmarkdown package is not available in this R installation.
      Install with install.packages("rmarkdown")

[>] Checking Python 3 installation....(None)

      Unable to locate an installed version of Python 3.
      Install Python 3 from https://www.python.org/downloads/

[>] Checking Julia installation...
ERROR: Dynamic Type-Checking Error: Invalid value 'installations' (valid values are install, info, knitr, jupyter, julia, versions, all).

Stack trace:
    at enforce (file:///C:/Users/cesar.castro/AppData/Local/Programs/Quarto/bin/quarto.js:163432:11)
    at enforceTargetType (file:///C:/Users/cesar.castro/AppData/Local/Programs/Quarto/bin/quarto.js:163451:48)
    at _Command.actionHandler (file:///C:/Users/cesar.castro/AppData/Local/Programs/Quarto/bin/quarto.js:163889:18)
    at async _Command.execute (file:///C:/Users/cesar.castro/AppData/Local/Programs/Quarto/bin/quarto.js:102102:7)
    at async _Command.parseCommand (file:///C:/Users/cesar.castro/AppData/Local/Programs/Quarto/bin/quarto.js:101979:14)
    at async quarto4 (file:///C:/Users/cesar.castro/AppData/Local/Programs/Quarto/bin/quarto.js:187653:5)
    at async file:///C:/Users/cesar.castro/AppData/Local/Programs/Quarto/bin/quarto.js:187681:5
    at async file:///C:/Users/cesar.castro/AppData/Local/Programs/Quarto/bin/quarto.js:187536:14
    at async mainRunner (file:///C:/Users/cesar.castro/AppData/Local/Programs/Quarto/bin/quarto.js:187538:5)
    at async file:///C:/Users/cesar.castro/AppData/Local/Programs/Quarto/bin/quarto.js:187674:3
Quarto 1.9.37
[>] Checking R installation...........OK
      Version: 4.5.3
      Path: C:/Users/cesar.castro/AppData/Local/Programs/R/R-4.5.3
      LibPaths:
        - C:/Users/cesar.castro/AppData/Local/Programs/R/R-4.5.3/library
      knitr: (None)
      rmarkdown: (None)

      The knitr package is not available in this R installation.
      Install with install.packages("knitr")
      The rmarkdown package is not available in this R installation.
      Install with install.packages("rmarkdown")

Quarto 1.9.37
[>] Checking Python 3 installation....(None)

      Unable to locate an installed version of Python 3.
      Install Python 3 from https://www.python.org/downloads/

PS C:\Users\cesar.castro\github\estatistica>

mcanouil · 2026-04-25T18:25:41Z

mcanouil
Apr 25, 2026
Collaborator

@czargab18 Could you provide the output of quarto check rather than "quarto check"? Could you also provide a reproducible example as a Git repository.

I'm converting as a GitHub discussion as this is more a "how to" than a bug report, especially since projects are by designed self-contained but you want to user external assets.
(Feature requests should also be made in discussions)

0 replies

czargab18 · 2026-04-26T01:01:09Z

czargab18
Apr 26, 2026
Author

Quarto + external assets + deploy sync (no public repo) — reproducible steps and evidence

I can’t make my full project public (or share some scripts) because it contains private/internal tooling and deployment-specific assets. However, I can provide:

the full output of quarto check (included below),
exact commands to render and deploy/sync,
the post-processing logs of the deploy sync tool, and
a “black-box repro” using the generated HTML before/after (I attached the two index.html files from book EST0033 specifically for a diff).

My setup intentionally separates authoring/build from deployment:

Authoring/build happens in: books/build/<BOOK>/ (sources: .qmd)
Quarto output is written to: books/book/<BOOK>/
Only at deploy time, I synchronize all rendered books from books/book into the final website root: public/book/

1) `quarto check` output (full)

PS C:\Users\cesar.castro\github\estatistica> quarto --version
>> quarto check
>> quarto check installations
>> quarto check knitr
>> quarto check jupyter
1.9.37
Quarto 1.9.37
[>] Checking environment information...
      Quarto cache location: C:\Users\cesar.castro\AppData\Local\quarto
[>] Checking versions of quarto binary dependencies...
      Pandoc version 3.8.3: OK
      Dart Sass version 1.87.0: OK
      Deno version 2.4.5: OK
      Typst version 0.14.2: OK
[>] Checking versions of quarto dependencies......OK
[>] Checking Quarto installation......OK
      Version: 1.9.37
      Path: C:\Users\cesar.castro\AppData\Local\Programs\Quarto\bin
      CodePage: 1252

[>] Checking tools....................OK
      TinyTeX: (not installed)
      Chromium: (not installed)
      Chrome Headless Shell: (not installed)
      VeraPDF: (not installed)

[>] Checking LaTeX....................OK
      Tex:  (not detected)

[>] Checking Chrome Headless....................OK
      Using: Chrome found on system
      Path: C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe
      Source: Windows Registry

[>] Checking basic markdown render....OK

[>] Checking R installation...........OK
      Version: 4.5.3
      Path: C:/Users/cesar.castro/AppData/Local/Programs/R/R-4.5.3
      LibPaths:
        - C:/Users/cesar.castro/AppData/Local/Programs/R/R-4.5.3/library
      knitr: (None)
      rmarkdown: (None)

      The knitr package is not available in this R installation.
      Install with install.packages("knitr")
      The rmarkdown package is not available in this R installation.
      Install with install.packages("rmarkdown")

[>] Checking Python 3 installation....(None)

      Unable to locate an installed version of Python 3.
      Install Python 3 from https://www.python.org/downloads/

[>] Checking Julia installation...
ERROR: Dynamic Type-Checking Error: Invalid value 'installations' (valid values are install, info, knitr, jupyter, julia, versions, all).

Stack trace:
    at enforce (file:///C:/Users/cesar.castro/AppData/Local/Programs/Quarto/bin/quarto.js:163432:11)
    at enforceTargetType (file:///C:/Users/cesar.castro/AppData/Local/Programs/Quarto/bin/quarto.js:163451:48)
    at _Command.actionHandler (file:///C:/Users/cesar.castro/AppData/Local/Programs/Quarto/bin/quarto.js:163889:18)
    at async _Command.execute (file:///C:/Users/cesar.castro/AppData/Local/Programs/Quarto/bin/quarto.js:102102:7)
    at async _Command.parseCommand (file:///C:/Users/cesar.castro/AppData/Local/Programs/Quarto/bin/quarto.js:101979:14)
    at async quarto4 (file:///C:/Users/cesar.castro/AppData/Local/Programs/Quarto/bin/quarto.js:187653:5)
    at async file:///C:/Users/cesar.castro/AppData/Local/Programs/Quarto/bin/quarto.js:187681:5
    at async file:///C:/Users/cesar.castro/AppData/Local/Programs/Quarto/bin/quarto.js:187536:14
    at async mainRunner (file:///C:/Users/cesar.castro/AppData/Local/Programs/Quarto/bin/quarto.js:187538:5)
    at async file:///C:/Users/cesar.castro/AppData/Local/Programs/Quarto/bin/quarto.js:187674:3
Quarto 1.9.37
[>] Checking R installation...........OK
      Version: 4.5.3
      Path: C:/Users/cesar.castro/AppData/Local/Programs/R/R-4.5.3
      LibPaths:
        - C:/Users/cesar.castro/AppData/Local/Programs/R/R-4.5.3/library
      knitr: (None)
      rmarkdown: (None)

      The knitr package is not available in this R installation.
      Install with install.packages("knitr")
      The rmarkdown package is not available in this R installation.
      Install with install.packages("rmarkdown")

Quarto 1.9.37
[>] Checking Python 3 installation....(None)

      Unable to locate an installed version of Python 3.
      Install Python 3 from https://www.python.org/downloads/

PS C:\Users\cesar.castro\github\estatistica>

Notes about the check output

I mistakenly ran quarto check installations (plural). It looks like the valid subcommand is quarto check install (singular). The error above is due to an invalid subcommand.
I’m not using knitr/rmarkdown features at the moment; R is installed but those packages are missing.
Quarto does not detect Python 3 in my environment. My Python tooling is used only for a separate deploy/post-processing step (not for Quarto execution via Jupyter).

2) Render steps (repro commands)

From the repository root:

quarto render books\build\EST0033

Directory convention:

Sources: books/build/<BOOK>/*.qmd
Quarto output: books/book/<BOOK>/

At this point, the book is correctly rendered, but it is still in the staging output folder (books/book/...).

3) Deploy-time synchronization + asset normalization (“sitemanager”)

Only at deploy time, I synchronize all rendered books from books/book/ into public/book/ and consolidate/normalize assets.

Command executed:

pnpm sitemanager --comp --update --books

Full log output:

PS C:\Users\cesar.castro\github\estatistica> .\pnpm sitemanager --comp --update --books

> estatistica-root@ sitemanager C:\Users\cesar.castro\github\estatistica
> pnpm --filter @estatistica/sitemanager cli "--comp" "--update" "--books"

> @estatistica/sitemanager@1.0.0 cli C:\Users\cesar.castro\github\estatistica\packages\sitemanager
> node ../../scripts/cli.js uv run sitemanager "--comp" "--update" "--books"

═══ PROCESSANDO LIVROS (SYNC + INDEX) ═══
> Iniciando BookManager v5 (Refatorado)...
[*] Iniciando sincronização de livros: C:\Users\cesar.castro\github\estatistica\books\book -> C:\Users\cesar.castro\github\estatistica\public\book
[*] Consolidando: EST0033/assets/ -> assets/
[*] Consolidando: TAS0000/assets/ -> assets/
[*] bootstrap.min.css atualizado
[*] bootstrap.min.css atualizado
[*] quarto-syntax-highlighting.css atualizado
[*] Processando 11 arquivos HTML...
[*] Mapeamento de assets: {'bootstrap-29782b9109293306ba0c0d21799b509c.min.css': 'bootstrap.min.css', 'bootstrap-2d04583987d51b702666a59ba20c7c2c.min.css': 'bootstrap.min.css', 'bootstrap-63fb1419b4f6e0e92ac83a74f71f09bc.min.css': 'bootstrap.min.css', 'quarto-syntax-highlighting-7f8f88aac4f3542376d5c11b86a4c14d.css': 'quarto-syntax-highlighting.css', 'quarto-syntax-highlighting-ed96de9b727972fe78a7b5d16c58bf87.css': 'quarto-syntax-highlighting.css'}
[*] Sincronização e processamento de livros concluídos.
[OK] Index atualizado com sucesso (Jinja2)!
[*] Processamento concluído.

════════════════════════════════════════════════════════════
  RESULTADOS
════════════════════════════════════════════════════════════

  Sucesso: 1
  Erro: 0
  Total: 1

PS C:\Users\cesar.castro\github\estatistica>

What the deploy post-processing does (black-box behavior)

Based on logs and observable output changes, this step:

Copies all book outputs from books/book/ → public/book/
Consolidates EST0033/assets/ and other books’ assets into a shared public/book/assets/
Normalizes Quarto hashed asset filenames (e.g. bootstrap-<hash>.min.css → bootstrap.min.css)
Rewrites HTML references for all processed HTML files to match the consolidated assets
Rebuilds an index page using Jinja2

4) Before/after evidence

I attached two HTML files from the rendered book EST0033:

index.before.html — produced by Quarto directly in books/book/EST0033/...
index.after.html — after synchronization + consolidation + HTML rewrite into public/book/...

These can be diffed to show exactly which <link>/<script> references were updated as part of the deploy sync.

5) How-to questions (guidance requested)

Given Quarto projects are designed to be self-contained, I understand this is a “how-to” question rather than a bug report.

I’d appreciate guidance on best practices for this workflow:

Is there a recommended Quarto-supported mechanism to post-process rendered HTML (hook, filter, documented pipeline step) for cases where outputs are relocated and assets consolidated?
Is it expected/acceptable to rewrite hashed assets → stable names (like bootstrap-<hash>.min.css → bootstrap.min.css) and patch HTML references, or is there a better approach in Quarto to produce stable asset filenames?
For deploying multiple books into a single public/ root (from multiple books/book/<BOOK> outputs), what’s the recommended way to keep Quarto asset paths consistent (quarto-html, bootstrap, search assets, etc.)?
Which GitHub account (username or organization) would you like me to grant access to for viewing the private repository, and should that access be temporary (if so, for how long)?

Thanks!

1 reply

mcanouil Apr 26, 2026
Collaborator

I can’t make my full project public (or share some scripts) because it contains private/internal tooling and deployment-specific assets

I did not ask for your real project.
I'm asking for a small reproducible example that matches your setup.
This is to ensure, the setup is the same and ease provide you with a solution.

post-render, pre-render (copy assets at render), symlinks/hardlinks, ...
"acceptable" is for you to define. Currently, Quarto does not have such mechanism to ensure deterministic output, especially across projects. Note that you can define project.lib-dir in youe _quarto.yml to store libraries at a specific location.
You can try things like this, but beware that they are likely to produce unexpected and unintended behaviours as assets were designed to be project specific:
```
project:
  type: book
  lib-dir: ../shared-lib
  output-dir: ../_site/book1-output
```
```
project:
  type: book
  lib-dir: ../shared-lib
  output-dir: ../_site/book2-output
```
There are none, so what works for your is the "recommended way".
See above. Do not share with me at least as there might be some conflict of interest. Better to create a small reproducible example that mimick your real project.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Quarto

Problems sharing assets among multiple Quarto books on custom domain (multi-book, one-assets) #14438

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 2 comments 1 reply

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Select a reply

Uh oh!

Quarto

Problems sharing assets among multiple Quarto books on custom domain (multi-book, one-assets) #14438

Uh oh!

Uh oh!

czargab18 Apr 25, 2026

I have:

Bug description

Bug description

Context

Hosting setup

Current workflow (workaround)

The problem

Steps to reproduce

Actual behavior

Expected behavior

Your environment

Quarto check output

Replies: 2 comments · 1 reply

Uh oh!

Uh oh!

mcanouil Apr 25, 2026 Collaborator

Uh oh!

Uh oh!

czargab18 Apr 26, 2026 Author

Quarto + external assets + deploy sync (no public repo) — reproducible steps and evidence

1) quarto check output (full)

Notes about the check output

2) Render steps (repro commands)

3) Deploy-time synchronization + asset normalization (“sitemanager”)

What the deploy post-processing does (black-box behavior)

4) Before/after evidence

5) How-to questions (guidance requested)

Uh oh!

Uh oh!

mcanouil Apr 26, 2026 Collaborator

czargab18
Apr 25, 2026

Replies: 2 comments 1 reply

mcanouil
Apr 25, 2026
Collaborator

czargab18
Apr 26, 2026
Author

1) `quarto check` output (full)

mcanouil Apr 26, 2026
Collaborator