Support `site_url` in great-docs.yml for subdirectory deployments
Difficulty: [2] IntermediateEffort: [2] MediumPriority: [3] HighType: ★ Enhancement
## 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
```bash
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:
```yaml
# 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.
关闭于 2026-05-07 5 条评论