doc: fix paths on 404 pages

[elijahgreenstein]

With the exception of the MicroCloud logo, the relative paths are not resolving correctly for href links and logo static files in the top navigation menu on 404 pages, nor are the resolving correctly for two "brand" href links (one in the sidebar and the other at the top of the page). Issues include:

• MicroCloud links in the top navigation menu, at the top of the page, and in the sidebar resolve to "#", which means that these links cannot be used to navigate back to the docs homepage.
• LXD, MicroCeph, and MicroOVN href links and static file paths in the to navigation menu resolve to the product (e.g. lxd/) or the tag path (e.g. lxd/_static/lxd_tag.png), which appends those paths to the end of the URL that lands on a 404 page (e.g. on canonical.com/microcloud/docs/latest/bad-url/, the LXD link goes to canonical.com/microcloud/docs/latest/bad-url/lxd/. As a result, the logos are not loading and the links cannot be used to navigate to the LXD, etc. docs subsets.

To resolve this issue, this commit:

• Adds nav404_prefix to html_context and sets it to the path portion of html_baseurl. This makes the base path available in HTML templates.
• Updates the MicroCloud header template with if-else statements, to use nav404_prefix on 404 pages. Note that only the MicroCloud header (microcloud.html) needed to be updated, since 404 pages across the integrated docs use the MicroCloud template (rather than to the LXD, MicroCeph, and MicroOVN subsets). This hard-codes the correct path into the 404 page generated by Sphinx.
• Updates the Makefile to replace "#" in the "brand" href links with the correct /microcloud/docs/{version} path.

Note that the Makefile update depends on the current docs URL pattern (https://canonical.com/microcloud/docs/{version}/ and will require a manual update if the docs move to a new URL pattern.

[elijahgreenstein]

Note that the 404 page will not render correctly in the RTD test build (this can be viewed by appending 404 to the end of the RTD build URL), since the URLs are all absolute paths that begin with /microcloud/docs/{version}/. This pattern works in the actual documentation at https://canonical.com/microcloud/docs/, but not in the RTD test build. However, I have checked the page source of the 404 page, and the updated paths all look correct to me, and align with other paths on the 404 page that are working correctly in the live documentation. For example, the navigation menu link to the tutorials has the path href="/microcloud/docs/1479/tutorial/", where 1479 is the "version" of the RTD test build. Likewise, the LXD top navigation menu path is now href="/microcloud/docs/1479/lxd/". The tutorial link on the active 404 page works; hence, I expect this LXD link to work as well.

[roosterfish]

Nice, thanks.

[roosterfish]

Can you re-trigger the build? Not sure why it is hanging.

[Copilot]

Pull request overview

This PR adjusts the Sphinx documentation build and templates so that integrated docs 404 pages use stable, absolute-ish paths for navigation links and logo assets, avoiding broken relative URLs when a 404 is served from an arbitrary URL.

Changes:

• Adds nav404_prefix to Sphinx html_context (derived from html_baseurl) for use in templates.
• Updates the MicroCloud integrated header template to use nav404_prefix specifically on the 404 page.
• Post-processes generated 404/index.html to replace href="#" in “brand” links with a versioned docs path.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
doc/Makefile	Adds 404 post-processing to rewrite brand links after building docs.
doc/conf.py	Exposes nav404_prefix in html_context for 404-specific template behavior.
doc/.sphinx/_integration/microcloud.html	Uses nav404_prefix for top-nav links and logos on 404 pages.

Suppressed comments (1)

doc/Makefile:165

• These commands use sed -i without a backup suffix, which is GNU-sed specific and fails on BSD/macOS sed. Making this portable avoids RTD/local build differences and reduces friction for contributors building docs on macOS.

	sed -i 's|<a href="#"><div class="brand">|<a href="$(NAV_404_HREF)"><div class="brand">|' "$(RTD_404_FILE)"
	sed -i 's|<a class="sidebar-brand" href="#">|<a class="sidebar-brand" href="$(NAV_404_HREF)">|' "$(RTD_404_FILE)"

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[elijahgreenstein]

Checked my sed updates in the RTD build and in a local build. URLs on the 404 page all look good.

[roosterfish]

Thanks!