Fix navigation in mdbook serve, PR preview, and production builds by converting relative paths to absolute

.github/workflows/gh-pages.yml

@@ -26,6 +26,9 @@ jobs:
 
       - run: mdbook build
 
+      - name: Fix navigation paths for production
+        run: ./inject-base-url.sh "" "./book"
+
       - name: Deploy
         uses: JamesIves/github-pages-deploy-action@v4.6.4
         with:

.github/workflows/preview.yml

@@ -32,10 +32,12 @@ jobs:
       - name: Build mdBook site
         run: mdbook build
         if: github.event.action != 'closed'
-        env:
-          MDBOOK_OUTPUT__HTML__SITE_URL: /pr-preview/pr-${{ github.event.number }}/
+
+      - name: Inject base URL for PR preview
+        run: ./inject-base-url.sh "/pr-preview/pr-${{ github.event.number }}/" "./book"
+        if: github.event.action != 'closed'
 
       - name: Deploy preview
-        uses: rossjrw/pr-preview-action@v1
+        uses: rossjrw/pr-preview-action@v1.6.3
         with:
           source-dir: ./book/

inject-base-url.sh

@@ -0,0 +1,92 @@
+#!/bin/bash
+# Script to inject <base href> tag into mdBook HTML output
+# Usage: ./inject-base-url.sh <base-url> <book-dir>
+
+set -e
+
+if [ $# -ne 2 ]; then
+    echo "Usage: $0 <base-url> <book-dir>"
+    echo "Example: $0 /pr-preview/pr-123/ ./book"
+    exit 1
+fi
+
+BASE_URL="$1"
+BOOK_DIR="$2"
+
+# Remove trailing slash for consistency in replacements
+BASE_URL="${BASE_URL%/}"
+
+# Validate inputs
+if [ ! -d "$BOOK_DIR" ]; then
+    echo "Error: Book directory '$BOOK_DIR' does not exist"
+    exit 1
+fi
+
+# Find all HTML files and prepend base URL to relative asset paths
+find "$BOOK_DIR" -name "*.html" -type f | while read -r html_file; do
+    # Get the directory of the current HTML file relative to book root
+    # This is needed for resolving ./ paths correctly
+    rel_dir=$(dirname "${html_file#$BOOK_DIR/}")
+
+    # Convert ../ relative paths to absolute paths with base URL
+    # This handles paths like: href="../../css/style.css" and href=".././theme/css/style.css"
+    sed -i -E "s|href=\"(\.\./)+|href=\"${BASE_URL}/|g" "$html_file"
+    sed -i -E "s|src=\"(\.\./)+|src=\"${BASE_URL}/|g" "$html_file"
+
+    # Clean up any remaining ./ that may have been left after ../ conversion
+    # This handles cases like ".././theme" which becomes "/base/./theme" and needs to be "/base/theme"
+    sed -i -E "s|href=\"${BASE_URL}/\./|href=\"${BASE_URL}/|g" "$html_file"
+    sed -i -E "s|src=\"${BASE_URL}/\./|src=\"${BASE_URL}/|g" "$html_file"
+
+    # Convert ./ relative paths to absolute paths with base URL
+    # This handles paths like: src="./image.png"
+    if [ "$rel_dir" = "." ]; then
+        # File is in root directory
+        sed -i -E "s|href=\"\./|href=\"${BASE_URL}/|g" "$html_file"
+        sed -i -E "s|src=\"\./|src=\"${BASE_URL}/|g" "$html_file"
+    else
+        # File is in subdirectory, need to include the subdirectory path
+        sed -i -E "s|href=\"\./|href=\"${BASE_URL}/${rel_dir}/|g" "$html_file"
+        sed -i -E "s|src=\"\./|src=\"${BASE_URL}/${rel_dir}/|g" "$html_file"
+    fi
+
+    # Convert simple relative paths (no ../ or ./) to absolute paths with base URL
+    # We need to distinguish between:
+    #   1. Root-relative paths (contain /): cloud/index.html → /base/cloud/index.html
+    #   2. File-relative paths (no /): migrating.html → /base/subdir/migrating.html
+    # Also handles paths with anchors: href="page.html#section" → href="/base/page.html#section"
+    # But avoid converting:
+    #   - already absolute paths (starting with /)
+    #   - URLs with schemes (http://, https://, mailto:, etc.) - they contain ":"
+    #   - standalone anchors (starting with #) - these don't start with letter/number
+
+    # First, handle root-relative paths (paths that contain at least one /)
+    # These are paths like "cloud/index.html" or "kion/features/getting_started.html"
+    sed -i -E "s|href=\"([a-zA-Z0-9][^\":]*)/([^\"]*)\"|href=\"${BASE_URL}/\1/\2\"|g" "$html_file"
+    sed -i -E "s|src=\"([a-zA-Z0-9][^\":]*)/([^\"]*)\"|src=\"${BASE_URL}/\1/\2\"|g" "$html_file"
+
+    # Special case: index.html in navigation always points to root, not relative directory
+    # This fixes the "Home" link in sidebar navigation
+    sed -i -E "s|href=\"index\.html\"|href=\"${BASE_URL}/index.html\"|g" "$html_file"
+
+    # Then, handle file-relative paths (simple filenames without /)
+    # Match paths that start with a letter or number, don't contain a colon or slash
+    # Exclude index.html as it's already handled above
+    if [ "$rel_dir" = "." ]; then
+        # File is in root directory
+        sed -i -E "s|href=\"([a-zA-Z0-9][^\"/:]*)\"|href=\"${BASE_URL}/\1\"|g" "$html_file"
+        sed -i -E "s|src=\"([a-zA-Z0-9][^\"/:]*)\"|src=\"${BASE_URL}/\1\"|g" "$html_file"
+    else
+        # File is in subdirectory, prepend the subdirectory path
+        sed -i -E "s|href=\"([a-zA-Z0-9][^\"/:]*)\"|href=\"${BASE_URL}/${rel_dir}/\1\"|g" "$html_file"
+        sed -i -E "s|src=\"([a-zA-Z0-9][^\"/:]*)\"|src=\"${BASE_URL}/${rel_dir}/\1\"|g" "$html_file"
+    fi
+
+    # Final cleanup: remove any remaining ./ in the middle of paths
+    # This handles cases like "/base/kion/features/./features/" which should be "/base/kion/features/features/"
+    sed -i -E "s|/\./|/|g" "$html_file"
+
+    echo "Converted paths in $(basename "$html_file")"
+done
+
+echo "Done! Prepended base URL '${BASE_URL}' to relative paths in '${BOOK_DIR}'"

src/kion/features/getting_started.md

@@ -6,7 +6,7 @@ The first thing you will see when you log into Kion is a dashboard. From here, y
 
 ## Access your Cloud Accounts
 
-The most common use for Kion is to access your cloud accounts. You will have one or more [Cloud Access Roles](./features/access_roles.md) assigned to each cloud account. These roles allow you to access the cloud account with various levels of permissions. It is best practice to always use the least-privileged role that allows you to perform the necessary actions.
+The most common use for Kion is to access your cloud accounts. You will have one or more [Cloud Access Roles](./access_roles.md) assigned to each cloud account. These roles allow you to access the cloud account with various levels of permissions. It is best practice to always use the least-privileged role that allows you to perform the necessary actions.
 
 You can access your accounts from many places in Kion, including the dashboard, the projects page, and the accounts page. Look for dropdown menus with a cloud icon to select the account and role you want to access.
 
@@ -42,7 +42,7 @@ When you select a project, you will have several options at the top of the page
 - **Financials** - This tab shows you the budget and spending status for the project. You can manage your budgets and generate reports and graphs. 
 - **Savings Opportunities** - This tab shows you ways to save money on your cloud spending. It will show you recommendations for Reserved Instances and other cost-saving opportunities.
 - **Enforcements** - This tab shows you and enforcements that are in place for the project. Enforcements are alerts or actions triggered by spending conditions, such as a budget being exceeded.
-- **Cloud Management** - This tab allows you to find more information about the Cloud Rules, [Cloud Access Roles](./features/access_roles.md), and related resources that are applied to the project.
+- **Cloud Management** - This tab allows you to find more information about the Cloud Rules, [Cloud Access Roles](./access_roles.md), and related resources that are applied to the project.
 - **Compliance** - This tab shows you the compliance posture of the project. It will show you any findings that are present, and give you recommendations on how to fix or suppress them.
 - **Users** - This tab shows you the users and groups that have access to the project. This access is separate from any Cloud Access Roles that are assigned to the accounts in the project.
 - **Permissions** - This tab shows you the permissions that users and groups have to the project, based on the settings in the Users tab.

theme/index.hbs

@@ -488,5 +488,86 @@
         {{/if}}
         {{/if}}
 
+        <!-- Navigation link fixing and active/expanded logic for mdBook 0.4.52 -->
+        <script type="text/javascript">
+        (function() {
+            // First, fix all relative navigation links to be absolute
+            // This makes navigation work correctly in mdbook serve without post-build scripts
+            var sidebarLinks = document.querySelectorAll("#sidebar a");
+            for (var i = 0; i < sidebarLinks.length; i++) {
+                var link = sidebarLinks[i];
+                var href = link.getAttribute("href");
+                if (!href) continue;
+
+                // Skip if already absolute (starts with /, http://, https://, or #)
+                if (href.startsWith("/") || href.startsWith("http://") || href.startsWith("https://") || href.startsWith("#")) {
+                    continue;
+                }
+
+                // Convert relative path to absolute
+                // Remove any ../ segments and prepend with /
+                var absolutePath = href;
+
+                // If href contains ../, we need to resolve it relative to current directory
+                if (absolutePath.indexOf("../") !== -1) {
+                    // Get current directory depth from path_to_root
+                    var depth = (path_to_root.match(/\.\.\//g) || []).length;
+
+                    // Remove all ../ from href and calculate actual path
+                    var upLevels = (absolutePath.match(/\.\.\//g) || []).length;
+                    absolutePath = absolutePath.replace(/\.\.\//g, "");
+
+                    // The remaining path is relative to root if we go up enough levels
+                    absolutePath = "/" + absolutePath;
+                } else if (absolutePath.indexOf("/") !== -1) {
+                    // Path like "cloud/index.html" - already relative to root
+                    absolutePath = "/" + absolutePath;
+                } else {
+                    // Simple filename like "index.html" - point to root
+                    absolutePath = "/" + absolutePath;
+                }
+
+                // Update the href
+                link.setAttribute("href", absolutePath);
+            }
+
+            // Now set active/expanded classes based on current page
+            var current_page = window.location.pathname;
+            if (current_page.endsWith("/")) {
+                current_page += "index.html";
+            }
+
+            var links = document.querySelectorAll("#sidebar a");
+            for (var i = 0; i < links.length; i++) {
+                var link = links[i];
+                var href = link.getAttribute("href");
+                if (!href) continue;
+
+                // Normalize the link href to compare with current page
+                var linkPath = href;
+                if (linkPath.startsWith(window.location.origin)) {
+                    linkPath = linkPath.substring(window.location.origin.length);
+                }
+
+                if (linkPath === current_page || (current_page.endsWith("/index.html") && linkPath === current_page.replace("/index.html", "/"))) {
+                    link.classList.add("active");
+                    var parent = link.parentElement;
+                    if (parent && parent.classList.contains("chapter-item")) {
+                        parent.classList.add("expanded");
+                    }
+                    while (parent) {
+                        if (parent.tagName === "LI" && parent.previousElementSibling) {
+                            if (parent.previousElementSibling.classList.contains("chapter-item")) {
+                                parent.previousElementSibling.classList.add("expanded");
+                            }
+                        }
+                        parent = parent.parentElement;
+                    }
+                    break;
+                }
+            }
+        })();
+        </script>
+
     </body>
 </html>