adding backup fonts for docs (#90)

Signed-off-by: Daniel Guns <danbguns@gmail.com>

Author: dgunzy

docs/assets/scss/_styles_project.scss

@@ -791,3 +791,71 @@ code:not(pre code) {
 * {
   transition: background-color 0.2s ease, color 0.2s ease, border-color 0.2s ease;
 }
+
+// Font Awesome fallbacks - ensure icons degrade gracefully when fonts are blocked
+// Add fallback font stack to prevent invisible icons
+.fab, .fas, .far {
+  // Ensure icons have minimum width to prevent layout shift
+  min-width: 1em;
+  display: inline-block;
+  text-align: center;
+  position: relative;
+}
+
+// Text fallbacks for icons - shown when fonts fail to load (via JavaScript detection)
+.icon-fallback-text {
+  display: none;
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+  font-size: 0.9em;
+  margin-left: 0.25em;
+  
+  // Show fallback text when fonts fail
+  .fonts-failed & {
+    display: inline;
+  }
+  
+  // Hide icon when showing fallback text
+  .fonts-failed + & {
+    display: inline;
+  }
+}
+
+// When fonts fail, hide icon and show text
+.fonts-failed {
+  .fab, .fas, .far {
+    // Make icon invisible but keep space
+    visibility: hidden;
+    width: 0;
+    min-width: 0;
+    margin: 0;
+  }
+  
+  .icon-fallback-text {
+    display: inline;
+  }
+}
+
+// Specific icon text fallbacks
+.fa-github + .icon-fallback-text::before {
+  content: '[GitHub]';
+}
+
+.fa-arrow-alt-circle-right + .icon-fallback-text::before {
+  content: '→';
+}
+
+.fa-box + .icon-fallback-text::before {
+  content: '[Box]';
+}
+
+.fa-beer + .icon-fallback-text::before {
+  content: '[Beer]';
+}
+
+.fa-moon + .icon-fallback-text::before {
+  content: '🌙';
+}
+
+.fa-sun + .icon-fallback-text::before {
+  content: '☀️';
+}

docs/assets/scss/_variables_project.scss

@@ -41,3 +41,7 @@ $link-hover-color: $purple-600;
 $border-radius: 0.5rem;
 $border-radius-sm: 0.25rem;
 $border-radius-lg: 0.75rem;
+
+// Font Awesome font path - ensure it points to the correct location
+// This should match where Hugo mounts the webfonts (static/webfonts)
+$fa-font-path: "../webfonts" !default;

docs/content/_index.md

@@ -25,10 +25,10 @@ notoc: true
     <!-- Action Buttons -->
     <div class="d-flex flex-wrap justify-content-center gap-3 mb-5">
       <a class="btn btn-lg btn-primary" href="{{< relref \"getting-started/\" >}}">
-        Get Started <i class="fas fa-arrow-alt-circle-right ms-2"></i>
+        Get Started <i class="fas fa-arrow-alt-circle-right ms-2" aria-label="Arrow"></i><span class="icon-fallback-text">→</span>
       </a>
       <a class="btn btn-lg btn-outline-primary" href="https://github.com/dgunzy/flux9s">
-        <i class="fab fa-github me-2"></i>View on GitHub
+        <i class="fab fa-github me-2" aria-label="GitHub"></i><span class="icon-fallback-text">[GitHub]</span><span>View on GitHub</span>
       </a>
     </div>
 

docs/layouts/partials/footer/left.html

@@ -0,0 +1,4 @@
+{{ if .Site.Params.links.user }}
+  {{ partial "footer/links.html" .Site.Params.links.user }}
+{{ end }}
+

docs/layouts/partials/footer/links.html

@@ -0,0 +1,18 @@
+<ul class="td-footer__links-list">
+  {{ range . }}
+  <li class="td-footer__links-item" data-bs-toggle="tooltip" title="{{ .name }}" aria-label="{{ .name }}">
+    <a target="_blank" rel="noopener" href="{{ .url }}" aria-label="{{ .name }}">
+      <i class="{{ .icon }}"></i>
+      {{/* Add fallback text for icons */}}
+      {{ if eq .icon "fab fa-github" }}
+        <span class="icon-fallback-text">[GitHub]</span>
+      {{ else if eq .icon "fas fa-box" }}
+        <span class="icon-fallback-text">[Box]</span>
+      {{ else if eq .icon "fas fa-beer" }}
+        <span class="icon-fallback-text">[Beer]</span>
+      {{ end }}
+    </a>
+  </li>
+  {{ end }}
+</ul>
+

docs/layouts/partials/head-custom.html

@@ -1,3 +1 @@
 {{- /* Custom head includes for flux9s docs */ -}}
-<script src="{{ "js/metadata.js" | relURL }}"></script>
-<script src="{{ "js/dark-mode.js" | relURL }}"></script>

docs/layouts/partials/navbar.html

@@ -25,7 +25,8 @@
     <div class="d-flex align-items-center ms-3">
       {{/* Dark mode toggle */}}
       <button class="theme-toggle btn btn-link text-decoration-none" id="theme-toggle" aria-label="Toggle dark mode" title="Toggle dark mode">
-        <i class="fas fa-moon" id="theme-icon"></i>
+        <i class="fas fa-moon" id="theme-icon" aria-hidden="true"></i>
+        <span class="sr-only">Toggle dark mode</span>
       </button>
     </div>
   </div>

docs/layouts/partials/scripts.html

@@ -1,3 +1,4 @@
 {{/* Custom scripts for flux9s docs - loaded at end of body */}}
+<script src="{{ "js/font-fallback.js" | relURL }}"></script>
 <script src="{{ "js/metadata.js" | relURL }}"></script>
 <script src="{{ "js/dark-mode.js" | relURL }}"></script>

docs/static/js/font-fallback.js

@@ -0,0 +1,69 @@
+// Font loading detection and fallback handling
+// Detects if Font Awesome fonts loaded successfully, shows text fallbacks if not
+
+(function() {
+  'use strict';
+  
+  // Check if Font Awesome fonts are available
+  function checkFontLoaded(fontFamily) {
+    if (!document.fonts || !document.fonts.check) {
+      // Fallback for browsers without Font Loading API
+      return false;
+    }
+    
+    // Check if the font is loaded
+    // Font Awesome 6 Free (solid) uses weight 900
+    // Font Awesome 6 Brands uses weight 400
+    if (fontFamily.includes('Free')) {
+      return document.fonts.check('900 1em "' + fontFamily + '"');
+    } else if (fontFamily.includes('Brands')) {
+      return document.fonts.check('400 1em "' + fontFamily + '"');
+    }
+    return false;
+  }
+  
+  // Wait for fonts to load, then check
+  function detectFontLoading() {
+    if (!document.fonts) {
+      // No Font Loading API - assume fonts might not load, show fallbacks
+      setTimeout(function() {
+        document.documentElement.classList.add('fonts-failed');
+      }, 2000);
+      return;
+    }
+    
+    // Wait for fonts to be ready
+    document.fonts.ready.then(function() {
+      // Check both Font Awesome font families
+      const freeLoaded = checkFontLoaded('Font Awesome 6 Free');
+      const brandsLoaded = checkFontLoaded('Font Awesome 6 Brands');
+      
+      // If either font failed to load, show fallbacks
+      if (!freeLoaded || !brandsLoaded) {
+        document.documentElement.classList.add('fonts-failed');
+        console.warn('Font Awesome fonts failed to load, showing text fallbacks');
+      }
+    }).catch(function() {
+      // If font loading fails, show fallbacks
+      document.documentElement.classList.add('fonts-failed');
+    });
+    
+    // Also set a timeout - if fonts don't load within 3 seconds, show fallbacks
+    setTimeout(function() {
+      const freeLoaded = checkFontLoaded('Font Awesome 6 Free');
+      const brandsLoaded = checkFontLoaded('Font Awesome 6 Brands');
+      
+      if (!freeLoaded || !brandsLoaded) {
+        document.documentElement.classList.add('fonts-failed');
+      }
+    }, 3000);
+  }
+  
+  // Run detection when DOM is ready
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', detectFontLoading);
+  } else {
+    detectFontLoading();
+  }
+})();
+

docs/static/js/metadata.js

@@ -1,46 +1,74 @@
 // Fetch and display project metadata
 (async function () {
+  // Helper to safely get element and set text
+  function safeSetText(elementId, text) {
+    try {
+      const el = document.getElementById(elementId);
+      if (el) {
+        el.textContent = text;
+      }
+    } catch (e) {
+      console.warn("Failed to update element:", elementId, e);
+    }
+  }
+  
+  // Helper to set default values
+  function setDefaults() {
+    safeSetText("crates-downloads", "-");
+    safeSetText("github-stars", "-");
+    safeSetText("github-downloads", "-");
+    safeSetText("github-releases", "-");
+  }
+  
   try {
     // Fetch metadata from our API endpoint (generated during build)
     const basePath =
       window.location.pathname.split("/").slice(0, -1).join("/") || "";
-    const response = await fetch(`${basePath}/metadata.json`);
+    const metadataUrl = `${basePath}/metadata.json`;
+    
+    // Use fetch with timeout
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 5000); // 5 second timeout
+    
+    const response = await fetch(metadataUrl, {
+      signal: controller.signal,
+      cache: 'no-cache'
+    });
+    
+    clearTimeout(timeoutId);
+    
     if (!response.ok) {
-      throw new Error("Failed to fetch metadata");
+      throw new Error(`Failed to fetch metadata: ${response.status} ${response.statusText}`);
     }
 
     const metadata = await response.json();
 
     // Update crates.io downloads
-    const cratesEl = document.getElementById("crates-downloads");
-    if (cratesEl && metadata.crates_downloads) {
-      cratesEl.textContent = formatNumber(metadata.crates_downloads);
+    if (metadata.crates_downloads !== undefined) {
+      safeSetText("crates-downloads", formatNumber(metadata.crates_downloads));
     }
 
     // Update GitHub stars
-    const starsEl = document.getElementById("github-stars");
-    if (starsEl && metadata.github_stars) {
-      starsEl.textContent = formatNumber(metadata.github_stars);
+    if (metadata.github_stars !== undefined) {
+      safeSetText("github-stars", formatNumber(metadata.github_stars));
     }
 
     // Update GitHub binary downloads
-    const downloadsEl = document.getElementById("github-downloads");
-    if (downloadsEl && metadata.github_binary_downloads) {
-      downloadsEl.textContent = formatNumber(metadata.github_binary_downloads);
+    if (metadata.github_binary_downloads !== undefined) {
+      safeSetText("github-downloads", formatNumber(metadata.github_binary_downloads));
     }
 
     // Update GitHub releases
-    const releasesEl = document.getElementById("github-releases");
-    if (releasesEl && metadata.github_releases) {
-      releasesEl.textContent = formatNumber(metadata.github_releases);
+    if (metadata.github_releases !== undefined) {
+      safeSetText("github-releases", formatNumber(metadata.github_releases));
     }
   } catch (error) {
-    console.error("Error loading metadata:", error);
-    // Set default values on error
-    document.getElementById("crates-downloads").textContent = "-";
-    document.getElementById("github-stars").textContent = "-";
-    document.getElementById("github-downloads").textContent = "-";
-    document.getElementById("github-releases").textContent = "-";
+    // Log error but don't break the page
+    if (error.name !== 'AbortError') {
+      console.warn("Error loading metadata (this is non-critical):", error.message);
+    }
+    // Set default values on error - these are already "-" by default in HTML
+    setDefaults();
   }
 })();