Docs: SEO, lychee hardening, custom 404, and gallery improvements

.github/workflows/docs.yml

@@ -15,6 +15,8 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0  # Full history for per-page last-updated dates
 
     # We build doxygen from source because of
     # https://github.com/doxygen/doxygen/issues/9016
@@ -35,6 +37,12 @@ jobs:
         cmake -S . -B build -G Ninja --install-prefix="$(pwd)/build/install" -D MFC_DOCUMENTATION=ON
         ninja -C build install
 
+    - name: Verify essential site files
+      run: |
+        for f in index.html 404.html robots.txt; do
+          test -f "build/install/docs/mfc/$f" || { echo "Missing $f"; exit 1; }
+        done
+
     - name: Upload Built Documentation Artifact
       uses: actions/upload-artifact@v4
       with:
@@ -51,20 +59,14 @@ jobs:
         base-url-path: https://mflowcode.github.io/
         path-to-root: build/install/docs/mfc
         include-pdf: false
-        sitemap-format: txt
+        sitemap-format: xml
 
     - name: Output stats
       run: |
         echo "sitemap-path = ${{ steps.sitemap.outputs.sitemap-path }}"
         echo "url-count = ${{ steps.sitemap.outputs.url-count }}"
         echo "excluded-count = ${{ steps.sitemap.outputs.excluded-count }}"
 
-    - name: Linkcheck - Lychee
-      uses: lycheeverse/lychee-action@v2
-      with:
-        args: -c .lychee.toml build/install/docs/mfc/
-        fail: false
-
     - name: Publish Documentation
       if:   github.repository == 'MFlowCode/MFC' && github.ref == 'refs/heads/master' &&  (github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' )
       run:  |
@@ -81,5 +83,11 @@ jobs:
         git -C ../www commit -m "Docs @ ${GITHUB_SHA::7}" || true
         git -C ../www push
 
+    - name: Linkcheck - Lychee
+      uses: lycheeverse/lychee-action@v2
+      with:
+        args: -c .lychee.toml build/install/docs/mfc/
+        fail: true
+
 # DOC_PUSH_URL should be of the format:
 # --> https://<username>:<token>@github.com/<username>/<repository>

.lychee.toml

@@ -16,5 +16,11 @@ accept = ["200", "429"]
 
 verbose = "error"
 
-# Exclude sitemap from link checking (it contains pre-publish production URLs)
-exclude_path = ["**/sitemap.txt"]
+# Exclude sitemap file from scanning (it contains pre-publish production URLs)
+exclude_path = ["sitemap\\.xml"]
+
+# Exclude URLs that fail due to external issues (broken SSL, pre-deploy only, etc.)
+exclude = [
+    "https://mflowcode\\.github\\.io/sitemap\\.xml",  # Only exists after deployment
+    "https://cpe\\.ext\\.hpe\\.com",                   # HPE Cray docs have broken SSL cert
+]

CMakeLists.txt

@@ -806,6 +806,25 @@ if (MFC_DOCUMENTATION)
     GEN_DOCS(post_process  "MFC: Post-Process")
     GEN_DOCS(documentation "MFC")
 
+    # Inject per-page last-updated dates into documentation markdown files.
+    # Runs after auto-generated .md files exist, before Doxygen processes them.
+    # Uses a stamp file so it only runs once per build.
+    add_custom_command(
+        OUTPUT  "${CMAKE_CURRENT_BINARY_DIR}/inject-dates.stamp"
+        DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/docs/documentation/examples.md"
+                "${CMAKE_CURRENT_SOURCE_DIR}/docs/documentation/case_constraints.md"
+                "${CMAKE_CURRENT_SOURCE_DIR}/docs/documentation/physics_constraints.md"
+                "${CMAKE_CURRENT_SOURCE_DIR}/docs/documentation/cli-reference.md"
+                "${CMAKE_CURRENT_SOURCE_DIR}/docs/documentation/parameters.md"
+        COMMAND "${Python3_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/docs/inject-dates.py"
+                "${CMAKE_CURRENT_SOURCE_DIR}"
+        COMMAND "${CMAKE_COMMAND}" -E touch "${CMAKE_CURRENT_BINARY_DIR}/inject-dates.stamp"
+        COMMENT "Injecting page dates into documentation"
+        VERBATIM
+    )
+    add_custom_target(inject_page_dates DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/inject-dates.stamp")
+    add_dependencies(documentation_doxygen inject_page_dates)
+
     # > Copy Resources (main landing page & assets)
     install(DIRECTORY   "${CMAKE_CURRENT_SOURCE_DIR}/docs/res"
             DESTINATION "docs/mfc")
@@ -814,6 +833,7 @@ if (MFC_DOCUMENTATION)
             DESTINATION "docs/mfc")
 
     install(FILES       "${CMAKE_CURRENT_SOURCE_DIR}/docs/index.html"
+                        "${CMAKE_CURRENT_SOURCE_DIR}/docs/404.html"
             DESTINATION "docs/mfc")
 endif()
 

docs/404.html

@@ -0,0 +1,28 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>404 | MFC</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css">
+</head>
+<body class="bg-slate-900 text-white min-h-screen flex flex-col items-center justify-center px-4">
+    <div class="text-center max-w-md">
+        <div class="text-8xl font-extrabold text-amber-400 mb-4">404</div>
+        <h1 class="text-2xl font-bold mb-2">Page not found</h1>
+        <p class="text-slate-400 mb-8">The page you're looking for doesn't exist or has been moved.</p>
+        <div class="flex flex-col sm:flex-row gap-4 justify-center">
+            <a href="/" class="px-6 py-3 bg-amber-400 text-slate-900 font-semibold rounded hover:bg-amber-300 transition-colors no-underline">
+                <i class="fa-solid fa-house mr-2"></i>Home
+            </a>
+            <a href="/documentation/" class="px-6 py-3 bg-slate-700 font-semibold rounded hover:bg-slate-600 transition-colors no-underline">
+                <i class="fa-solid fa-book mr-2"></i>Documentation
+            </a>
+            <a href="https://github.com/MFlowCode/MFC" class="px-6 py-3 bg-slate-700 font-semibold rounded hover:bg-slate-600 transition-colors no-underline">
+                <i class="fa-brands fa-github mr-2"></i>GitHub
+            </a>
+        </div>
+    </div>
+</body>
+</html>

docs/header.html

@@ -18,7 +18,8 @@
 <meta name="viewport" content="width=device-width, initial-scale=1"/>
 <!--BEGIN PROJECT_NAME--><title>$projectname: $title</title><!--END PROJECT_NAME-->
 <!--BEGIN !PROJECT_NAME--><title>$title</title><!--END !PROJECT_NAME-->
-<meta name=”keywords” content="exascale, fluid dynamics, cfd, computational fluid dynamics, compressible, hpc, bryngelson, colonius, subgrid, multiphase, frontier, summit, el capitan, aurora, amd gpu, gpu, nvidia"/>
+<meta name="description" content="$title — MFC documentation. Open-source exascale multiphase flow solver." />
+<meta name="keywords" content="exascale, fluid dynamics, cfd, computational fluid dynamics, compressible, hpc, bryngelson, colonius, subgrid, multiphase, frontier, summit, el capitan, aurora, amd gpu, gpu, nvidia"/>
 <link href="$relpath^tabs.css" rel="stylesheet" type="text/css"/>
 <script type="text/javascript" src="$relpath^jquery.js"></script>
 <script type="text/javascript" src="$relpath^dynsections.js"></script>

docs/index.html

@@ -23,20 +23,54 @@
     <meta property="og:url" content="https://mflowcode.github.io" />
     <meta property="og:type" content="website" />
     <meta name="twitter:card" content="summary_large_image" />
+    <script type="application/ld+json">
+    {
+      "@context": "https://schema.org",
+      "@type": "SoftwareSourceCode",
+      "name": "MFC",
+      "alternateName": "Multi-Component Flow Code",
+      "description": "Open-source exascale multiphase flow solver. 2025 Gordon Bell Prize Finalist. Scales to 200+ trillion grid points on 43,000+ GPUs.",
+      "url": "https://mflowcode.github.io",
+      "license": "https://opensource.org/licenses/MIT",
+      "programmingLanguage": ["Fortran", "Python"],
+      "codeRepository": "https://github.com/MFlowCode/MFC",
+      "author": {
+        "@type": "Organization",
+        "name": "MFlowCode",
+        "url": "https://github.com/MFlowCode"
+      },
+      "award": "2025 ACM Gordon Bell Prize Finalist"
+    }
+    </script>
     <script src="https://cdn.tailwindcss.com"></script>
     <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css">
     <link rel="icon" type="image/x-icon" href="res/icon.ico">
     <script>
         const sims = [
-            { name: "Viscous Taylor-Green vortex",       image: "res/simulations/h.png", computer: "Delta",   accelerators: "128 A100s", walltime: "17h",     source: "https://www.youtube.com/watch?v=7i2h08dlDQw" },
-            { name: "Shedding water droplet",            image: "res/simulations/a.png", computer: "Summit",  accelerators: "960 V100s", walltime: "4h",      source: "https://www.youtube.com/watch?v=Gjj-qZkXcrg" },
-            { name: "Flow over an airfoil (vorticity)",  image: "res/simulations/g.png", computer: "Delta",   accelerators: "128 A100s", walltime: "19h",     source: "https://www.youtube.com/watch?v=FvAgnBW59cY" },
-            { name: "Cavitation fragments kidney stone", image: "res/simulations/d.png", computer: "Summit",  accelerators: "576 V100s", walltime: "30 min",  source: "https://doi.org/10.48550/arXiv.2305.09163" },
-            { name: "Breakup of vibrated interface",     image: "res/simulations/f.png", computer: "Summit",  accelerators: "128 V100s", walltime: "4h",      source: "https://www.youtube.com/watch?v=XQ3g1oSg8mc" },
-            { name: "Mach 2 flow over a sphere",         image: "res/simulations/i.png", computer: "Phoenix", accelerators: "36 V100s",  walltime: "30m",     source: "https://www.youtube.com/watch?v=HQGSUvYEGqM" },
-            { name: "Mach 2 shear layer",                image: "res/simulations/j.png", computer: "Phoenix", accelerators: "32 V100s",  walltime: "15m",     source: "https://www.youtube.com/watch?v=GtcdCHLmJO8" },
-            { name: "Collapsing bubbles (pressure)",     image: "res/simulations/b.png", computer: "Summit",  accelerators: "216 V100s", walltime: "3h",      source: "https://doi.org/10.48550/arXiv.2305.09163" },
-            { name: "Collapsing bubbles (streamlines)",  image: "res/simulations/c.png", computer: "Summit",  accelerators: "216 V100s", walltime: "3h",      source: "https://doi.org/10.48550/arXiv.2305.09163" },
+            // Rockets & jets
+            { name: "Mach 12 Starship Super Heavy",      image: "res/simulations/o.png", computer: "Alps",     computerUrl: "https://www.cscs.ch/computers/alps/",                                          accelerators: "5K GH200s", walltime: "18h",     source: "https://www.youtube.com/watch?v=NSn3OVF8N4I" },
+            { name: "Mach 10 triple jet booster",        image: "res/simulations/n.png", computer: "Frontier", computerUrl: "https://www.olcf.ornl.gov/frontier/",                                          accelerators: "10K GCDs",  walltime: "12h",     source: "https://www.youtube.com/watch?v=pMUl55xqGgM" },
+            { name: "Mach 2 flow over a sphere",         image: "res/simulations/i.png", computer: "Phoenix",  computerUrl: "https://www.pace.gatech.edu/",                                                 accelerators: "36 V100s",  walltime: "30m",     source: "https://www.youtube.com/watch?v=HQGSUvYEGqM" },
+            { name: "Mach 2 shear layer",                image: "res/simulations/j.png", computer: "Phoenix",  computerUrl: "https://www.pace.gatech.edu/",                                                 accelerators: "32 V100s",  walltime: "15m",     source: "https://www.youtube.com/watch?v=GtcdCHLmJO8" },
+            // Aerodynamics
+            { name: "Flow over an airfoil (vorticity)",  image: "res/simulations/g.png", computer: "Delta",    computerUrl: "https://www.ncsa.illinois.edu/research/project-highlights/delta/",              accelerators: "128 A100s", walltime: "19h",     source: "https://www.youtube.com/watch?v=FvAgnBW59cY" },
+            { name: "Pitching airfoil (3D)",             image: "res/simulations/m.png", computer: "Phoenix",  computerUrl: "https://www.pace.gatech.edu/",                                                 accelerators: "1 A100",    walltime: "5h",      source: "https://www.youtube.com/watch?v=2XH-9MumDHU" },
+            // Shock-droplet
+            { name: "Shedding water droplet",            image: "res/simulations/a.png", computer: "Summit",   computerUrl: "https://www.olcf.ornl.gov/summit/",                                            accelerators: "960 V100s", walltime: "4h",      source: "https://www.youtube.com/watch?v=Gjj-qZkXcrg" },
+            // Biomedical & acoustics
+            { name: "Burstwave lithotripsy",             image: "res/simulations/k.png", computer: "Delta",    computerUrl: "https://www.ncsa.illinois.edu/research/project-highlights/delta/",              accelerators: "128 A100s", walltime: "30m",     source: "https://www.youtube.com/watch?v=XWsUTaJXGF8" },
+            { name: "Cavitation fragments kidney stone", image: "res/simulations/d.png", computer: "Summit",   computerUrl: "https://www.olcf.ornl.gov/summit/",                                            accelerators: "576 V100s", walltime: "30m",  source: "https://doi.org/10.48550/arXiv.2305.09163" },
+            { name: "Kidney stone stress waves",         image: "res/simulations/l.png", computer: "Bridges2", computerUrl: "https://www.psc.edu/resources/bridges-2/",                                      accelerators: "8 V100s",   walltime: "20m",     source: "https://www.youtube.com/watch?v=Q2L0J68qnRw" },
+            { name: "Whale bubble net feeding",          image: "res/simulations/p.png", computer: "Delta",    computerUrl: "https://www.ncsa.illinois.edu/research/project-highlights/delta/",              accelerators: "128 A100s", walltime: "30m",     source: "https://www.youtube.com/watch?v=6EpP6tdCZSA" },
+            { name: "Earplug acoustics (kinetic energy)", image: "res/simulations/q.png", computer: "Delta",    computerUrl: "https://www.ncsa.illinois.edu/research/project-highlights/delta/",              accelerators: "8 A100s",   walltime: "5h",      source: "https://www.youtube.com/watch?v=xSW5wZkdbrc" },
+            { name: "Circular orifice (1 kHz)",          image: "res/simulations/r.png", computer: "Delta",    computerUrl: "https://www.ncsa.illinois.edu/research/project-highlights/delta/",              accelerators: "16 A100s",  walltime: "5h",      source: "https://www.youtube.com/watch?v=jOhJ_c7eco4" },
+            // Bubble dynamics
+            { name: "Collapsing bubbles (pressure)",     image: "res/simulations/b.png", computer: "Summit",   computerUrl: "https://www.olcf.ornl.gov/summit/",                                            accelerators: "216 V100s", walltime: "3h",      source: "https://doi.org/10.48550/arXiv.2305.09163" },
+            { name: "Collapsing bubbles (streamlines)",  image: "res/simulations/c.png", computer: "Summit",   computerUrl: "https://www.olcf.ornl.gov/summit/",                                            accelerators: "216 V100s", walltime: "3h",      source: "https://doi.org/10.48550/arXiv.2305.09163" },
+            { name: "Euler-Lagrange particle cloud",     image: "res/simulations/s.png", computer: "Phoenix",  computerUrl: "https://www.pace.gatech.edu/",                                                 accelerators: "8 A100s",   walltime: "<1h",     source: "https://www.youtube.com/watch?v=RoT-yC5Lxmg" },
+            // Fundamentals
+            { name: "Breakup of vibrated interface",     image: "res/simulations/f.png", computer: "Summit",   computerUrl: "https://www.olcf.ornl.gov/summit/",                                            accelerators: "128 V100s", walltime: "4h",      source: "https://www.youtube.com/watch?v=XQ3g1oSg8mc" },
+            { name: "Viscous Taylor-Green vortex",       image: "res/simulations/h.png", computer: "Delta",    computerUrl: "https://www.ncsa.illinois.edu/research/project-highlights/delta/",              accelerators: "128 A100s", walltime: "17h",     source: "https://www.youtube.com/watch?v=7i2h08dlDQw" },
         ];
 
         const scalings = [
@@ -54,14 +88,14 @@
                             <img class="h-10" src="res/logo.png" alt="">
                         </div>
                         <div class="flex-1 p-2 font-semibold text-center">${s.name}</div>
-                        <a class="w-10 text-center" href="${s.source}">
-                            <i class="fa-solid fa-arrow-up-right-from-square"></i>
+                        <a class="w-10 text-center text-xl" href="${s.source}" target="_blank">
+                            <i class="${s.source.includes('youtube.com') ? 'fa-brands fa-youtube' : 'fa-solid fa-arrow-up-right-from-square'}"></i>
                         </a>
                     </div>
                     <div class="grid grid-cols-3 gap-4 px-4 py-2">
                         <div class="flex flex-row items-center">
                             <div class="pr-2"><i class="fa-solid fa-server"></i></div>
-                            <div class="flex-1 text-center">${s.computer}</div>
+                            <div class="flex-1 text-center">${s.computerUrl ? `<a href="${s.computerUrl}" class="underline hover:text-amber-400" target="_blank">${s.computer}</a>` : s.computer}</div>
                         </div>
                         <div class="flex flex-row items-center">
                             <div class="pr-2"><i class="fa-solid fa-microchip"></i></div>
@@ -76,12 +110,12 @@
             `).join("");
 
             document.getElementById("ft-scaling").innerHTML = scalings.map(s => `
-                <div class="flex md:w-2/6 mx-auto flex-col text-white rounded bg-slate-900 rounded-b-lg">
+                <a href="documentation/expectedPerformance.html" class="flex md:w-2/6 mx-auto flex-col text-white rounded bg-slate-900 rounded-b-lg hover:ring-2 hover:ring-amber-400 transition-shadow no-underline">
                     <div class="flex-1 grid bg-white pb-2">
                         <img class="place-self-center" src="${s.image}" alt="${s.label}">
                     </div>
                     <div class="flex-1 p-2 font-semibold text-center">${s.label}</div>
-                </div>
+                </a>
             `).join("");
 
             fetch("https://api.github.com/repos/MFlowCode/MFC/releases/latest")

docs/inject-dates.py

@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+"""Inject last-updated dates into docs before Doxygen runs.
+
+Usage: python3 inject-dates.py [source_dir]
+  source_dir defaults to current directory.
+"""
+import subprocess
+import sys
+from pathlib import Path
+from datetime import date
+
+src_dir = Path(sys.argv[1]) if len(sys.argv) > 1 else Path(".")
+docs_dir = src_dir / "docs" / "documentation"
+
+for md_file in sorted(docs_dir.glob("*.md")):
+    if "Page last updated:" in md_file.read_text():
+        continue
+
+    result = subprocess.run(
+        ["git", "log", "-1", "--format=%as", "--", str(md_file)],
+        capture_output=True, text=True,
+        cwd=str(src_dir),
+    )
+    page_date = result.stdout.strip() or str(date.today())
+
+    with open(md_file, "a") as f:
+        f.write(
+            f"\n\n<div style='text-align:center; font-size:0.75rem; "
+            f"color:#888; padding:16px 0 0;'>"
+            f"Page last updated: {page_date}</div>\n"
+        )

docs/robots.txt

@@ -1,4 +1,4 @@
 User-agent: *
 Allow: /
 
-Sitemap: https://mflowcode.github.io/sitemap.txt
+Sitemap: https://mflowcode.github.io/sitemap.xml