[Bug]: All assets are 404 when deployed to github pages

[alexhelms]

docmd version

0.8.11

Node.js version

v24.15.0

OS/Browser

Windows / Edge

Description

I upgraded from v0.8.9 to v0.8.11 and when I deployed to github pages everything assets is 404. I'm using the default github page url, so https://alexhelms.github.io/some-project/ but the items that are 404'ing (css, images, etc.) are requesting https://alexhelms.github.io/assets/css/docmd-main.css, note the missing some-project repo path in the URL.

When running v0.8.9 this worked fine, however custom images in /assets/images also showed this same behavior when deployed. I had the following in markdown:

![Dashboard](/assets/images/screenshot-dashboard.png){ .lightbox  }

This worked running locally but when deployed to GH pages the repo name was missing in the URL so the image was broken.

Upgrading to v0.8.11 broke everything in assets.

Here are the relevant sections in docmd.config.json:

{
  "url": "https://alexhelms.github.io/some-project",
  "src": "docs",
  "out": "site",
  "base": "/",
}

Please let me know if you need any additional information, configs, etc. happy to help!

Steps to Reproduce

Upgrade a GH Pages deployed docmd project from v0.8.9 to v0.8.11.

Expected Behavior

Assets should be resolved correctly.

[mgks]

Hi @alexhelms, thanks for the report. This is a confirmed regression introduced in 0.8.10.

What happened: In 0.8.10 we added a <base href="/"> tag to the HTML layout to fix a separate issue where assets 404'd when a page was served without a trailing slash. That tag tells the browser to resolve all relative URLs against the domain root. For your setup deploying at https://alexhelms.github.io/some-project/, the browser now strips the /some-project/ prefix and looks for assets at https://alexhelms.github.io/assets/... instead of https://alexhelms.github.io/some-project/assets/....

In 0.8.9 there was no <base> tag, so the browser resolved relative paths against the document's actual location, which happened to work correctly even without explicit subpath config.

Immediate fix: Set base to match your GitHub Pages subpath:

{
  "url": "https://alexhelms.github.io/some-project",
  "base": "/some-project/"
}

The trailing slash matters in 0.8.11. This makes the <base> tag emit <base href="/some-project/"> and all assets resolve correctly.

Proper fix coming: I'm working on auto-detecting the deployment path from your url config when base is not explicitly set, so this "just works" for GitHub Pages project sites without manual config. This will ship in 0.8.12 tonight, you can also update to that directly without touching your config or try the above fix for instant solution.

Apologies for the breakage on upgrade. I should have caught this, your config was reasonable and worked before, so the regression is on our side.

[alexhelms]

Thank you for the fast response but the fix doesn't seem to be working completely for me. I'm noticing two issues after updating to v0.8.12:

1. Local dev now has 404 links to all assets. It seems to be inserting the repo name in the URL. E.g. http://127.0.0.1:3000/my-repo/assets/css/docmd-main.css which isn't valid for local dev. The page content is there, but none of the css/js/etc.
2. When deployed to github pages, the assets are loading on the main page. Selecting another page works since it is an SPA, but if you open a specific doc page as its own tab then the assets do not load and are missing the repo name in the URL path.

[mgks]

the fix doesn't seem to be working

Actually, I started working on 0.9.0 alongside this, so the current fix ended up being bundled with a few related changes that were still being tested. It looks like the Summer template also has an issue with the auto-install path, so there's a bit more to untangle than I initially thought.

Thanks for reporting it back. For now, I'd recommend using the base workaround in 0.8.11 if you can. Give me a little more time to test everything properly, and I'll aim to ship 0.8.13 within the next day or two. 🤞🏼

It gets a bit overwhelming juggling multiple release branches at the same time, but I'll make sure we get this fixed properly rather than rushing out another incomplete patch.

[mgks]

@alexhelms, just released 0.8.13 with a few more fixes and thoroughly tested it across a variety of scenarios, including offline builds and different CI environments. I'm really hoping this finally puts the issue to rest.

When you get a chance, could you give it another try and let me know if it's working properly now, or if you're still running into any issues? It would be really helpful. Thanks!