Publish Mendix Docs to Siemens Support Center

_scripts/add-index-html-links.sh

@@ -0,0 +1,85 @@
+#!/bin/bash
+# Post-processing script for Siemens internal deployment.
+# Rewrites directory-style href links (ending with /) to explicit /index.html
+# links in all HTML files under public/, so the Siemens server can serve them
+# without requiring automatic directory index support.
+#
+# When built with the siemens-internal environment, canonifyURLs=true causes Hugo
+# to expand all internal links to full absolute URLs using the baseURL. Pass that
+# baseURL as the second argument so those links are rewritten too.
+#
+# Rewrites both plain directory links and directory links with anchors:
+#   href=".../path/"           → href=".../path/index.html"
+#   href=".../path/#anchor"    → href=".../path/index.html#anchor"
+#
+# Skips:
+#   - External links (contain :// but do not start with base-url)
+#   - Anchor-only links starting with #
+#   - Links already containing index.html or ending in .html/.htm
+#
+# Usage: bash _scripts/add-index-html-links.sh [public-dir] [base-url]
+# Default public-dir: public
+# Default base-url: (empty — only root-relative and relative links are rewritten)
+#
+# Example (siemens-internal build):
+#   bash _scripts/add-index-html-links.sh public \
+#     https://internal.docs.sw.siemens.com/documentation/internal/PL20260323299104942/en-US/Mendix-Docs/public/
+
+set -euo pipefail
+
+PUBLIC_DIR="${1:-public}"
+BASE_URL="${2:-}"
+
+if [ ! -d "$PUBLIC_DIR" ]; then
+    echo "Error: directory '$PUBLIC_DIR' not found. Run hugo build first." >&2
+    exit 1
+fi
+
+echo "Adding index.html to directory links in $PUBLIC_DIR..."
+[ -n "$BASE_URL" ] && echo "Treating '$BASE_URL' as internal base URL."
+
+python3 - "$PUBLIC_DIR" "$BASE_URL" << 'PYTHON'
+import re, sys
+from pathlib import Path
+
+public_dir = sys.argv[1]
+base_url = sys.argv[2].rstrip("/") + "/" if sys.argv[2] else ""
+
+HREF_RE = re.compile(r"""(href=["'])([^"']*)(["'])""")
+
+def rewrite_href(m):
+    pre, url, quote = m.group(1), m.group(2), m.group(3)
+
+    # Treat absolute URLs that start with base_url as internal; skip all others
+    if "://" in url:
+        if not (base_url and url.startswith(base_url)):
+            return m.group(0)
+
+    # Skip anchor-only links
+    if url.startswith("#"):
+        return m.group(0)
+
+    # Split off any fragment (e.g. /path/#anchor → path=/path/, fragment=#anchor)
+    fragment = ""
+    if "#" in url:
+        url, fragment = url.split("#", 1)
+        fragment = "#" + fragment
+
+    # Skip already-explicit file links
+    if url.endswith(".html") or url.endswith(".htm"):
+        return f"{pre}{url}{fragment}{quote}"
+
+    if url.endswith("/"):
+        url = url + "index.html"
+    return f"{pre}{url}{fragment}{quote}"
+
+count = 0
+for path in Path(public_dir).rglob("*.html"):
+    original = path.read_text(encoding="utf-8", errors="replace")
+    updated = HREF_RE.sub(rewrite_href, original)
+    if updated != original:
+        path.write_text(updated, encoding="utf-8")
+        count += 1
+
+print(f"Updated {count} HTML files.")
+PYTHON

_scripts/fix-siemens-paths.sh

@@ -0,0 +1,9 @@
+#!/bin/bash
+# Post-processing script for Siemens internal deployment
+# NOTE: As of Hugo v0.156.0, the doubled-path bug has been fixed.
+# This script is kept for backwards compatibility but no longer performs any actions.
+
+echo "Siemens internal deployment post-processing..."
+echo "✓ Hugo v0.156.0+ correctly handles deep baseURL paths"
+echo "✓ No file copying needed - all asset references are correct"
+echo "Done!"

assets/scss/_font-face.scss

@@ -1,53 +1,53 @@
 @font-face { // LZ - Added for MxDock by request 2024-01-30
     font-family: "noto-sans";
-    src: local("noto-sans"), url("/fonts/noto-sans/noto-sans-400.woff2") format("woff2");
+    src: local("noto-sans"), url("../fonts/noto-sans/noto-sans-400.woff2") format("woff2");
     font-style: normal;
     font-weight: 400;
     font-display: swap;
   }
-  
+
   @font-face {
     font-family: "noto-sans";
-    src: local("noto-sans"), url("/fonts/noto-sans/noto-sans-400-italic.woff2") format("woff2");
+    src: local("noto-sans"), url("../fonts/noto-sans/noto-sans-400-italic.woff2") format("woff2");
     font-style: italic;
     font-weight: 400;
     font-display: swap;
   }
-  
+
   @font-face {
     font-family: "noto-sans";
-    src: local("noto-sans"), url("/fonts/noto-sans/noto-sans-600.woff2") format("woff2");
+    src: local("noto-sans"), url("../fonts/noto-sans/noto-sans-600.woff2") format("woff2");
     font-style: normal;
     font-weight: 600;
     font-display: swap;
   }
-  
+
   @font-face {
     font-family: "noto-sans";
-    src: local("noto-sans"), url("/fonts/noto-sans/noto-sans-600-italic.woff2") format("woff2");
+    src: local("noto-sans"), url("../fonts/noto-sans/noto-sans-600-italic.woff2") format("woff2");
     font-style: italic;
     font-weight: 600;
     font-display: swap;
   }
-  
+
   /* Medium */
   @font-face {
     font-family: "Patron";
     font-style: normal;
     font-weight: 500;
     font-display: swap;
     src: local("Patron Medium"), local("Patron-Medium"),
-      url("/fonts/patron/PatronWEB-Medium.woff2") format("woff2");
+      url("../fonts/patron/PatronWEB-Medium.woff2") format("woff2");
   }
-  
+
   /* Light */
   @font-face {
     font-family: "Patron";
     font-style: normal;
     font-weight: 300;
     font-display: swap;
     src: local("Patron Light"), local("Patron-Light"),
-      url("/fonts/patron/PatronWEB-Light.woff2") format("woff2");
+      url("../fonts/patron/PatronWEB-Light.woff2") format("woff2");
   }
 
   /* The main font is Noto Sans */

config/siemens-internal/INDEX-HTML-WORKAROUND.md

@@ -0,0 +1,157 @@
+# Adding index.html to Directory Links for Siemens Deployment
+
+## The Problem
+
+The Siemens internal web server does not automatically serve `index.html` when a directory URL is requested. When a user or browser requests `https://internal.docs.sw.siemens.com/documentation/internal/PL20260323299104942/en-US/Mendix-Docs/public/refguide/`, the server does not automatically serve the `refguide/index.html` file.
+
+Hugo's `uglyURLs = true` setting helps by making URLs explicit where possible, but Hugo still generates many directory-style links (ending with `/`) throughout the site, particularly in:
+
+* Navigation menus
+* Breadcrumbs
+* Internal page links
+* Table of contents
+
+## Recommended Solution: Post-Processing
+
+The cleanest approach is to post-process the HTML files after Hugo builds them, rewriting directory links to explicitly include `/index.html`.
+
+### How It Works
+
+1. **Hugo builds the site normally** using the siemens-internal environment
+2. **Post-processing script runs** and:
+   * Scans all HTML files in the `public/` directory
+   * Identifies internal links that end with `/` (directory links)
+   * Rewrites them to end with `/index.html`
+   * Preserves external links, anchor links, and explicit file references unchanged
+
+3. **Resulting HTML has explicit paths** that the Siemens server can serve correctly
+
+### Link Transformation Examples
+
+**Navigation links:**
+
+```html
+<!-- Before -->
+<a href="https://internal.docs.sw.siemens.com/documentation/internal/PL20260323299104942/en-US/Mendix-Docs/public/refguide/">
+
+<!-- After -->
+<a href="https://internal.docs.sw.siemens.com/documentation/internal/PL20260323299104942/en-US/Mendix-Docs/public/refguide/index.html">
+```
+
+**Breadcrumb links:**
+
+```html
+<!-- Before -->
+<a href="/documentation/internal/PL20260323299104942/en-US/public/deployment/">
+
+<!-- After -->
+<a href="/documentation/internal/PL20260323299104942/en-US/public/deployment/index.html">
+```
+
+### What Gets Changed
+
+✅ **Internal directory links**: `href=".../"` → `href=".../index.html"`
+✅ **Internal directory links with anchors**: `href=".../#section"` → `href=".../index.html#section"`
+
+❌ **External links**: `href="https://example.com/..."` (unchanged)
+❌ **Anchor-only links**: `href="#section"` (unchanged)
+❌ **File links**: `href=".../page.html"` (unchanged)
+❌ **Protocol links**: `href="mailto:..."`, `href="javascript:..."` (unchanged)
+
+### Implementation Approach
+
+The post-processing can be implemented using standard text processing tools:
+
+**Option 1: Using sed (bash)**
+
+* Fast and simple for straightforward pattern matching
+* May require careful escaping of special characters
+* Best for simple, well-defined patterns
+
+**Option 2: Using a scripting language (Python/Node.js)**
+
+* More reliable HTML parsing
+* Better handling of edge cases
+* Can use proper HTML parsers (BeautifulSoup, cheerio, etc.)
+* More maintainable for complex transformations
+
+**Option 3: Using specialized tools (htmlq, pup)**
+
+* Purpose-built for HTML manipulation
+* Balance between sed simplicity and full scripting power
+
+### Integration with Build Process
+
+Update the build workflow to:
+
+```bash
+# Build the site
+hugo --environment siemens-internal --cleanDestinationDir
+
+# Post-process to add index.html to directory links
+bash _scripts/add-index-html-links.sh public \
+  https://internal.docs.sw.siemens.com/documentation/internal/PL20260323299104942/en-US/Mendix-Docs/public/
+```
+
+The script is kept in `_scripts/` alongside the existing (now no-op) `fix-siemens-paths.sh`.
+
+### Advantages
+
+* ✅ **Non-invasive**: Does not require modifying Hugo templates or Docsy theme files
+* ✅ **Environment-specific**: Only affects siemens-internal builds
+* ✅ **Maintainable**: Clear separation between Hugo build and Siemens-specific processing
+* ✅ **Reversible**: Disable by skipping the post-processing step
+* ✅ **Hugo-version independent**: Works regardless of Hugo updates
+* ✅ **Preserves other outputs**: Standard HTML and print versions remain unchanged
+
+### Disadvantages
+
+* ❌ **Build-time overhead**: Adds processing time (likely 5-30 seconds depending on implementation)
+* ❌ **Two-step process**: Requires running a script after Hugo build
+* ❌ **Pattern matching complexity**: Must identify which links to transform precisely
+
+## Alternative Solution: Hugo Render Hooks and Custom Layouts
+
+Instead of post-processing, modify Hugo's rendering behavior at build time.
+
+### How It Works
+
+1. **Create custom render hooks** for Markdown links in `.layouts/_default/_markup/`
+2. **Override navigation partials** from Docsy theme to append `/index.html`
+3. **Configure hooks** to only apply for siemens-internal environment
+
+### Required Changes
+
+* Copy Docsy navigation partial files to local `layouts/` directory
+* Modify link generation logic to append `/index.html` to directory URLs
+* Create Markdown render hooks for content links
+* Add conditional logic to check environment
+
+### Advantages
+
+* ✅ **Build-time only**: No post-processing step required
+* ✅ **Single build command**: Just run `hugo --environment siemens-internal`
+
+### Disadvantages
+
+* ❌ **More invasive**: Requires copying and modifying theme files
+* ❌ **Maintenance burden**: Must update custom layouts when Docsy updates
+* ❌ **Complexity**: Multiple layout files need modification
+* ❌ **Testing required**: Must verify all link types work correctly
+* ❌ **Harder to isolate**: Siemens-specific logic mixed with layout code
+
+## Recommendation
+
+Use the **post-processing approach** because:
+
+1. Hugo v0.156.0 already eliminated the need for the previous doubled-path workaround, and the post-processing approach proved straightforward to implement
+2. The script can be kept simple and focused on one task
+3. It does not require maintaining customized Docsy theme files
+4. It is easier to test, debug, and modify
+5. It keeps the Siemens-specific logic isolated and well-documented
+
+The slight increase in build time is acceptable for a deployment that happens infrequently, and the maintainability benefits outweigh the minor inconvenience of a two-step build process.
+
+## Status
+
+This solution has been implemented. The script is at `_scripts/add-index-html-links.sh` and the build steps are documented in `config/siemens-internal/README.md`.