Skip to content

Internal documentation routing

This page explains how the documentation hub is exposed on docs.omnivoltaic.com, why some URLs can show 404, and how to avoid broken navigation between sites.

Canonical URLs

What URL pattern
Documentation hub (this site) https://docs.omnivoltaic.com/internal/consolidated-docs/
Apex shortcut (Worker-dependent) https://docs.omnivoltaic.com/ — often mapped to the same hub
Other internal MkDocs sites https://docs.omnivoltaic.com/internal/<repo>/

Links in this hub use /internal/<repo>/... paths so they match the Cloudflare Worker and stay consistent in global search.

Why /internal/ alone can 404

The Worker matches /internal/<repo>/... where <repo> is a non-empty segment (for example consolidated-docs, oves-finance). The path /internal/ with nothing after the second slash does not map to a project and may fall through to a proxy that requests a non-existent path on the Pages origin → 404.

Do not rely on https://docs.omnivoltaic.com/internal/ (no repo) as a page URL—it is not a valid project path. Use the Hub home at:

  • https://docs.omnivoltaic.com/ — recommended front door (see the hub index.md for the short “Internal documentation” explanation).

The hub is also available under /internal/consolidated-docs/ if you need a path under /internal/* (for example Access policies).

Add this at the start of fetch (right after const path = url.pathname;), before isProjectStaticPath and any proxyToPages. It only matches bare /internal and /internal/—not /internal/oves-finance/ or any other repo.

if (path === '/internal' || path === '/internal/') {
  return Response.redirect(`${url.origin}/`, 302);
}
  • Effect: Visitors who type /internal or /internal/ land on the hub home (/), where the “Internal documentation” section explains the /internal/<repo>/ pattern.
  • Other sites: Unchanged. Only those two exact paths redirect.

Deploy this in the same Worker that proxies docs.omnivoltaic.com.

  1. Repo key — The segment after /internal/ must exist in the Worker’s route table (same name as the Cloudflare Pages project mapping).
  2. Trailing slashes — Prefer links with a trailing slash for directory-style MkDocs URLs (Material), or follow redirects.
  3. Renamed repos — Update mkdocs.yml nav and curation/curated-doc-sites.yml together when a project slug changes.
  4. Global search — The hub bundles docs/assets/global-doc-search-index.json; if search fails on deep pages, ensure the latest hub build is deployed (asset path resolution is fixed in hub JavaScript for production).