The problem
I'm hosting my great-docs site on an on-prem server where the site lives
at a subpath:
http://myserver:3838/data-team/mypackage/
Quarto generates root-relative asset paths by default (/site_libs/...,
/reference/..., etc.). When you're not at the root, every CSS, JS, and
navigation link 404s — the site is cooked, looks broken and the entire reference
section doesn't show up.
The standard Quarto fix is as simpl as setting website.site-url in
_quarto.yml. But since great-docs owns and regenerates _quarto.yml on every
build, any manual edit gets silently wiped. There's no clean way to persist this.
What I'm doing now
great-docs build
# Patch the generated _quarto.yml before re-rendering
python3 -c "
import pathlib
p = pathlib.Path('great-docs/_quarto.yml')
t = p.read_text()
if 'site-url' not in t:
t = t.replace('website:', 'website:\n site-url: \"http://myserver:3838/data_analytics/mypackage\"', 1)
p.write_text(t)
"
# Re-render with the correct base path
quarto render great-docs/It works, but it feels hacky and it doubles the render time, depends on the
website: key being formatted a specific way
The fix
A site_url key in great-docs.yml that gets written into the generated
_quarto.yml automatically during build:
# great-docs.yml
site_url: "http://myserver:3838/data_analytics/mypackage"
That's literally it!
FYI anyone not deploying to GitHub Pages or a dedicated domain is likely hitting this. They
just might not know why the site looks broken.
The problem
I'm hosting my great-docs site on an on-prem server where the site lives
at a subpath:
Quarto generates root-relative asset paths by default (
/site_libs/...,/reference/..., etc.). When you're not at the root, every CSS, JS, andnavigation link 404s — the site is cooked, looks broken and the entire reference
section doesn't show up.
The standard Quarto fix is as simpl as setting
website.site-urlin_quarto.yml. But since great-docs owns and regenerates_quarto.ymlon everybuild, any manual edit gets silently wiped. There's no clean way to persist this.
What I'm doing now
It works, but it feels hacky and it doubles the render time, depends on the
website:key being formatted a specific wayThe fix
A
site_urlkey ingreat-docs.ymlthat gets written into the generated_quarto.ymlautomatically during build:That's literally it!
FYI anyone not deploying to GitHub Pages or a dedicated domain is likely hitting this. They
just might not know why the site looks broken.