Multiple rendered html Quarto Books cannot be put under a single local web server.

mickeykawai commented 2 hours ago

Bug description

Upon request by cderv at Posit Community (https://forum.posit.co/t/is-there-an-easy-way-or-option-to-host-multiple-rendered-html-quarto-books-under-a-single-local-web-server/186888/4), I re-post the issue here.

Bug:

Multiple rendered html Quarto Books cannot be set under a single local web server by default.

Workaround:

Add a post-render script in yml file and put the script by hand, to add <base href="..."> tag during Render HTML (e.g. <base href="http://localhost:3000/mybook2/">.
- Or just modifying the index.html by hand to add the tag manually is enough.

Steps to reproduce

The mybook1 and mybook2 contents are uploaded as Archive.zip below.

Procedure:

`mybook1` (where default QuartoBook behavior does not work)

On RStudio.app on macOS, File > New Project ... > New Directory > Quarto Book > mybook1 (at any directory you like).
Open index.qmd
Hit Render (Render HTML).

`mybook2` (where my script is added and `_quarto.yml` is modified to include `project: post-render:` before Render)

On RStudio.app on macOS, File > New Project ... > New Directory > Quarto Book > mybook2 (at any directory you like).
Add scripts/add-base.sh in the mybook2/ directory.
- add-base.sh:

#!/bin/bash
mv _book/index.html _book/index.orig.html
name=$(basename "$(pwd)")
perl -spe 's!\<head\>\n!\<head\>\n\<base href\="http://localhost:3000\/$name/">\n!;' -- -name=$name _book/index.orig.html > _book/index.html
ln -s -f "$(pwd)"/_book ~/Sites/$name
#cd ~/Sites
#npx serve .
#http://localhost:3000

Open _quarto.yml

Add following two lines after type: book (l.2)

post-render: 
  - scripts/add-base.sh

Whole quarto.yml is now as follows.

project:
  type: book
  post-render: 
    - scripts/add-base.sh

book:
  title: "mybook2"
  author: "Norah Jones"
  date: "10/19/2024"
  chapters:
    - index.qmd
    - intro.qmd
    - summary.qmd
    - references.qmd

bibliography: references.bib

format:
  html:
    theme: cosmo
  pdf:
    documentclass: scrreprt

Open index.qmd
Hit Render (Render HTML).

Difference between the original `index.html` and the one post-rendered.

% diff index.html index.orig.html 
3d2
< <base href="http://localhost:3000/mybook2/">

Soft link the two quarto books in html to `~/Sites/` (where you set up web server document root).

mkdir ~/Sites
cd ~/Sites
ln -s <your_mybook1_topdir>/_book mybook1
ln -s <your_mybook1_topdir>/_book mybook2
# It is not necessary to do these `ln -s` commands by hand if you used above mentioned `add-base.sh` file as it also does this step.

~/Sites % ls -lh
total 0
lrwxr-xr-x  1 <account>  staff    57B Oct 19 17:46 mybook1 -> <working_dir>/mybook1/_book
lrwxr-xr-x@ 1 <account>  staff    57B Oct 19 17:45 mybook2 -> <working_dir>/mybook2/_book
~/Sites %

Examine on browser.

Start web server

cd ~/Sites
npx serve .
# npx serve /Users/<your_account>/Sites

Open browser
Enter url as http://localhost:3000
Click the link of mybook1 and mybook2.

Archive.zip

Expected behavior

HTML is formatted correctly with JS search functionality working.

Actual behavior

HTML is not formatted correctly.

Your environment

macOS Sonoma 14.7 (on M2mac)
RStudio.app Version 2024.09.0+375 (2024.09.0+375)
R.app R version 4.4.0 (2024-04-24) -- "Puppy Cup"
Chrome.app Version 129.0.6668.101 (Official Build) (arm64)

Quarto check output

$ quarto check
Quarto 1.5.57
[✓] Checking versions of quarto binary dependencies...
      Pandoc version 3.2.0: OK
      Dart Sass version 1.70.0: OK
      Deno version 1.41.0: OK
      Typst version 0.11.0: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
      Version: 1.5.57
      Path: /Applications/RStudio.app/Contents/Resources/app/quarto/bin

[✓] Checking tools....................OK
      TinyTeX: (external install)
      Chromium: (not installed)

[✓] Checking LaTeX....................OK
      Using: TinyTex
      Path: /Users/<account_name>/Library/TinyTeX/bin/universal-darwin
      Version: 2023

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

[✓] Checking Python 3 installation....OK
      Version: 3.9.6
      Path: /Applications/Xcode.app/Contents/Developer/usr/bin/python3
      Jupyter: 5.5.0
      Kernels: python3

[✓] Checking Jupyter engine render....OK

[✓] Checking R installation...........OK
      Version: 4.4.0
      Path: /Library/Frameworks/R.framework/Resources
      LibPaths:
        - /Library/Frameworks/R.framework/Versions/4.4-arm64/Resources/library
      knitr: 1.47
      rmarkdown: 2.27

[✓] Checking Knitr engine render......OK

$

mcanouil commented 2 hours ago

You need to set site-url to the root of your book as described in the documentation https://quarto.org/docs/websites/website-navigation.html#non-root-site-paths (it's also described in few other places such as https://quarto.org/docs/reference/projects/books.html)

If you don't set it, then the default is to take the root of the domain which of course will break your site/book if it is not at the root.

mickeykawai commented 1 hour ago

I tried two yml where I added site-url: <url> as below but either does not work.

Procedure.

I added the site-url: <url> just below the book: in yml.
- This modification of yml by hand is done before hitting Render HTML.
- Other steps are the same as the one for mybook1 described as above.
- The mybook3 and mybook4 contents are attached as Archive 2.zip below.

`mybook3` where `site-url: http://localhost:3000/mybook3` is added.

_quarto.yml

project:
  type: book

book:
  site-url: http://localhost:3000/mybook3
  title: "mybook3"
  author: "Norah Jones"
  date: "10/19/2024"
  chapters:
    - index.qmd
    - intro.qmd
    - summary.qmd
    - references.qmd

bibliography: references.bib

format:
  html:
    theme: cosmo
  pdf:
    documentclass: scrreprt

`mybook4` where `site-url: http://localhost:3000` is added.

_quarto.yml

project:
  type: book

book:
  site-url: http://localhost:3000
  title: "mybook4"
  author: "Norah Jones"
  date: "10/19/2024"
  chapters:
    - index.qmd
    - intro.qmd
    - summary.qmd
    - references.qmd

bibliography: references.bib

format:
  html:
    theme: cosmo
  pdf:
    documentclass: scrreprt

Results

~/Sites % ls -lh
total 0
lrwxr-xr-x  1 mickey  staff    57B Oct 19 17:46 mybook1 -> <working_dir>/mybook1/_book
lrwxr-xr-x@ 1 mickey  staff    57B Oct 19 17:45 mybook2 -> <working_dir>/mybook2/_book
lrwxr-xr-x  1 mickey  staff    57B Oct 19 18:38 mybook3 -> <working_dir>/mybook3/_book
lrwxr-xr-x  1 mickey  staff    57B Oct 19 18:41 mybook4 -> <working_dir>/mybook4/_book
~/Sites %

Archive 2.zip

mcanouil commented 9 minutes ago

I cannot reproduce. Note that your workflow is not really simple.

Create a project:

quarto create project book Issue-11115 Issue-11115

Modify _quarto.yml:

project:
 type: book
 output-dir: ../docs/subfolder

book:
 site-url: subfolder
 title: "subfolder"
 author: "Norah Jones"
 date: "10/19/2024"
 chapters:
   - index.qmd
   - intro.qmd
   - summary.qmd
   - references.qmd

bibliography: references.bib

format:
 html:
   theme: cosmo
 pdf:
   documentclass: scrreprt

Render the project:
```
quarto render
```
Setup GitHub Pages to deploy the site.
Check out the perfectly rendered book: https://m.canouil.dev/quarto-cli-11115/subfolder/

Repository: https://github.com/mcanouil/quarto-cli-11115

To me, the issue is in your workflow rather than in Quarto.

quarto-dev / quarto-cli