Summary
On a sub-path deployment (base: '/next-bun-compile' + site), every URL Nimbus constructs itself drops base, while Astro's own asset URLs are fine. The site renders and looks correct, but navigation is entirely dead and code blocks lose all syntax highlighting — there is no build error or warning.
grep -c BASE_URL node_modules/@cloudflare/nimbus-docs/dist/index.js → 0. The compiled package that produces the sidebar tree, breadcrumbs and pagination has no base awareness at all; NimbusHead.astro is the only place with a withBase helper, and two of its own lines bypass it.
I know about #77 (merged, in 0.10.0 — canonical/og/JSON-LD/sitemap-link are indeed correct in my build) and #78 (closed 2026-08-28, i.e. after 0.11.0 shipped on 2026-08-20, so its fix is unreleased and I can't verify it). Everything below is outside the scope of both.
Environment
@cloudflare/create-nimbus-docs 0.6.6 (templates-v0.6.6), @cloudflare/nimbus-docs 0.11.0 (latest on npm), astro 7.0.9- macOS arm64, bun,
output: "static", --deploy other --content empty
Repro
npx @cloudflare/create-nimbus-docs@latest spike --yes --deploy other --content empty --package-manager bun
cd spike
# astro.config.ts: site: "https://example.github.io", base: "/spike"
bun run build && bunx astro preview --port 4340
Then request the URLs the build emitted. All of these 404; the same resources all return 200 at the base-prefixed path.
| Surface |
Emitted |
Expected |
| Favicon |
/spikefavicon.ico |
/spike/favicon.ico |
| Shiki stylesheet |
/spike_nimbus/shiki.css |
/spike/_nimbus/shiki.css |
| Every sidebar link |
/getting-started/ |
/spike/getting-started/ |
| Breadcrumb "Home" |
/ |
/spike/ |
| Header logo link |
/ |
/spike/ |
Note the first two are not merely missing the prefix — they are concatenated without a separator, because import.meta.env.BASE_URL has no trailing slash. The favicon and the syntax-highlighting stylesheet are therefore 404 on every page of a sub-path site.
The sitemap additionally emits a spurious /spike/index/ entry alongside both /spike and /spike/.
Root cause
1. NimbusHead.astro bypasses its own helper. The file defines a correct withBase() at line 92 (from #77) and uses it for the LLM index, version canonical, social image, JSON-LD and sitemap link. But two lines build hrefs by raw interpolation instead:
// src/components/NimbusHead.astro:171
const faviconHref = `${import.meta.env.BASE_URL}${matchedFavicon.file}`;
// src/components/NimbusHead.astro:216
const shikiCssHref = `${import.meta.env.BASE_URL}_nimbus/shiki.css${import.meta.env.DEV ? `?v=${Date.now()}` : ""}`;Both should be withBase("/favicon.ico") / withBase("/_nimbus/shiki.css"), which also fixes the missing separator since withBase normalises the trailing slash.
2. The sidebar/breadcrumb/pagination tree is built base-less. SidebarLink.astro renders href verbatim from the tree returned by getSidebar(), and the compiled package contains no BASE_URL reference, so those hrefs are site-relative-without-base by construction. This is the same class of bug as #78 but for navigation rather than .md/llms URLs, and it is the one that makes a sub-path site unusable.
3. Starter hardcodes /. src/components/Header.astro:37 is a literal <a href="/">. User-owned code, so trivially patchable — but the scaffold ships it broken for every sub-path user.
Suggested fix
#78's recommendation was to consolidate the ad-hoc withBase implementations into one shared, exported helper. That would resolve this too, provided it is also applied to the sidebar tree builder (the highest-impact case, and currently entirely base-unaware) and re-used by the starter templates instead of literal /. Exporting it publicly would also let those of us with sub-path sites patch our own copied components consistently.
Impact
GitHub Pages project sites are the common case here (user.github.io/<repo>), and they are currently not viable on Nimbus: no working navigation, no favicon, and unstyled code blocks. Root deployments are unaffected — my other Nimbus site is at a domain root and is completely fine.
Summary
On a sub-path deployment (
base: '/next-bun-compile'+site), every URL Nimbus constructs itself dropsbase, while Astro's own asset URLs are fine. The site renders and looks correct, but navigation is entirely dead and code blocks lose all syntax highlighting — there is no build error or warning.grep -c BASE_URL node_modules/@cloudflare/nimbus-docs/dist/index.js→ 0. The compiled package that produces the sidebar tree, breadcrumbs and pagination has no base awareness at all;NimbusHead.astrois the only place with awithBasehelper, and two of its own lines bypass it.I know about #77 (merged, in 0.10.0 — canonical/og/JSON-LD/sitemap-link are indeed correct in my build) and #78 (closed 2026-08-28, i.e. after 0.11.0 shipped on 2026-08-20, so its fix is unreleased and I can't verify it). Everything below is outside the scope of both.
Environment
@cloudflare/create-nimbus-docs0.6.6 (templates-v0.6.6),@cloudflare/nimbus-docs0.11.0 (latest on npm),astro7.0.9output: "static",--deploy other --content emptyRepro
Then request the URLs the build emitted. All of these 404; the same resources all return 200 at the
base-prefixed path./spikefavicon.ico/spike/favicon.ico/spike_nimbus/shiki.css/spike/_nimbus/shiki.css/getting-started//spike/getting-started///spike///spike/Note the first two are not merely missing the prefix — they are concatenated without a separator, because
import.meta.env.BASE_URLhas no trailing slash. The favicon and the syntax-highlighting stylesheet are therefore 404 on every page of a sub-path site.The sitemap additionally emits a spurious
/spike/index/entry alongside both/spikeand/spike/.Root cause
1.
NimbusHead.astrobypasses its own helper. The file defines a correctwithBase()at line 92 (from #77) and uses it for the LLM index, version canonical, social image, JSON-LD and sitemap link. But two lines build hrefs by raw interpolation instead:Both should be
withBase("/favicon.ico")/withBase("/_nimbus/shiki.css"), which also fixes the missing separator sincewithBasenormalises the trailing slash.2. The sidebar/breadcrumb/pagination tree is built base-less.
SidebarLink.astrorendershrefverbatim from the tree returned bygetSidebar(), and the compiled package contains noBASE_URLreference, so those hrefs are site-relative-without-base by construction. This is the same class of bug as #78 but for navigation rather than.md/llms URLs, and it is the one that makes a sub-path site unusable.3. Starter hardcodes
/.src/components/Header.astro:37is a literal<a href="/">. User-owned code, so trivially patchable — but the scaffold ships it broken for every sub-path user.Suggested fix
#78's recommendation was to consolidate the ad-hoc
withBaseimplementations into one shared, exported helper. That would resolve this too, provided it is also applied to the sidebar tree builder (the highest-impact case, and currently entirely base-unaware) and re-used by the starter templates instead of literal/. Exporting it publicly would also let those of us with sub-path sites patch our own copied components consistently.Impact
GitHub Pages project sites are the common case here (
user.github.io/<repo>), and they are currently not viable on Nimbus: no working navigation, no favicon, and unstyled code blocks. Root deployments are unaffected — my other Nimbus site is at a domain root and is completely fine.