Fix rspress base path for GitHub Pages sub-path deployment#73
Merged
Conversation
GitHub Pages serves this project at https://jrs1986.github.io/CodingScaffold/, a sub-path. rspress was emitting asset URLs at the apex (e.g. /static/css/styles.css) which resolved to jrs1986.github.io/static/... and 404'd — leaving the deployed site rendered as unstyled HTML with a giant raw GitHub SVG. Setting base: '/CodingScaffold/' in rspress.config.ts makes the generator prefix every emitted href/src so assets resolve at the right URL. Verified locally: doc_build/index.html now references /CodingScaffold/static/css/... etc. Trailing slash matters — rspress normalizes URLs against it. The local `npm run dev` server still works because rspress strips base when serving from 127.0.0.1.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The bug
The deployed docs site rendered as raw HTML — no CSS, giant unstyled GitHub SVG taking over the page. Classic "CSS didn't load" symptoms.
Cause: GitHub Pages serves this project site at `https://jrs1986.github.io/CodingScaffold/\` (a sub-path under the account-level apex). rspress was emitting asset URLs at the apex:
```
href="/static/css/styles.a229748ab8.css" # resolves to https://jrs1986.github.io/static/... ← 404
```
Confirmed by `curl -s https://jrs1986.github.io/CodingScaffold/ | grep href` against the deployed HTML.
The fix
One line in `docs/rspress.config.ts`:
```ts
base: '/CodingScaffold/',
```
After this, the generator prefixes every emitted `href`/`src`:
```
href="/CodingScaffold/static/css/styles.a229748ab8.css" ← resolves correctly
```
Verification
Local build inspects:
```
$ cd docs && npm ci && npm run build
$ grep -oE 'href="[^\"]\.css"|src="[^\"]\.js"' doc_build/index.html | head -3
href="/CodingScaffold/static/css/styles.a229748ab8.css"
src="/CodingScaffold/static/js/styles.817d7b47ee.js"
src="/CodingScaffold/static/js/lib-react.dd63507a08.js"
```
Trailing slash on `base` matters — rspress normalizes URLs against it.
After merge, the next push to `main` triggers `docs.yml`, which redeploys with the corrected base path. The site at https://jrs1986.github.io/CodingScaffold/ should style up immediately.
Local dev still works
`npm run dev` at `127.0.0.1:3000` still serves at the root (rspress strips `base` for the local dev server), so no change for local writers.