Make GH Pages deployment create symlinks rather than redirects

This change makes the GH pages deployment create symlinks for all
un-leveled shortnames, pointing to the appropriate leveled shortnames —
eliminating the need for the web server to do any rewrites, and
eliminating the need for any redirects (either server- or client-side).
Thus, it replaces the existing build mechanism that generated index.html
files containing client-side redirects.

Author: sideshowbarker

.github/workflows/build-specs.yml

@@ -53,7 +53,7 @@ jobs:
           for file in ./**/Overview.html; do
             cp "$file" "$(dirname "$file")/index.html"
           done
-      - name: Build index & redirects
+      - name: Build index & symlinks
         run: python ./bin/build-index.py
       - run: rm -rf ./.git{,attributes,ignore}
 

bin/build-index.py

@@ -108,27 +108,15 @@ def get_html_spec_metadata(folder_name, path):
     }
 
 
-def build_redirect(shortname, spec_folder):
-    """Builds redirects from the shortname to the current work for that spec.
-
-    Since Github Actions doesn't allow anything like mod_rewrite, we do this by
-    creating an empty index.html in the shortname folder that redirects to the
-    correct spec.
+def create_symlink(shortname, spec_folder):
+    """Creates a <shortname> symlink pointing to the given <spec_folder>.
     """
 
-    template = jinja_env.get_template("redirect.html.j2")
-    contents = template.render(spec_folder=spec_folder)
-
-    folder = os.path.join(".", shortname)
     try:
-        os.mkdir(folder)
-    except FileExistsError:
+        os.symlink(spec_folder, shortname)
+    except OSError:
         pass
 
-    index = os.path.join(folder, "index.html")
-    with open(index, mode='w', encoding="UTF-8") as f:
-        f.write(contents)
-
 
 CURRENT_WORK_EXCEPTIONS = {
     "css-conditional": 5,
@@ -148,7 +136,7 @@ def build_redirect(shortname, spec_folder):
 specgroups = defaultdict(list)
 
 for entry in os.scandir("."):
-    if entry.is_dir():
+    if entry.is_dir(follow_symlinks=False):
         # Not actual specs, just examples.
         if entry.name in ["css-module"]:
             continue
@@ -172,7 +160,7 @@ def build_redirect(shortname, spec_folder):
 for shortname, specgroup in specgroups.items():
     if len(specgroup) == 1:
         if shortname != specgroup[0]["dir"]:
-            build_redirect(shortname, specgroup[0]["dir"])
+            create_symlink(shortname, specgroup[0]["dir"])
     else:
         specgroup.sort(key=lambda spec: spec["level"])
 
@@ -194,9 +182,9 @@ def build_redirect(shortname, spec_folder):
             currentWorkDir = specgroup[-1]["dir"]
 
         if shortname != currentWorkDir:
-            build_redirect(shortname, currentWorkDir)
+            create_symlink(shortname, currentWorkDir)
         if shortname == "css-snapshot":
-            build_redirect("css", currentWorkDir)
+            create_symlink("css", currentWorkDir)
 
 with open("./index.html", mode='w', encoding="UTF-8") as f:
     template = jinja_env.get_template("index.html.j2")

bin/templates/index.html.j2

@@ -55,12 +55,8 @@
 
 <ul>
   {% for shortname, specgroup in specgroups|dictsort %}
-  {% if specgroup|count == 1 %}
-  {% set spec = specgroup[0] %}
-  <li><a href="./{{ spec.dir }}">{{ spec.title }}</a></li>
-  {% else %}
   <li>
-    <p>{{ shortname }}</p>
+    <p><a href="./{{ shortname }}">{{ shortname }}</a></p>
     <ul>
       {% for spec in specgroup %}
       <li><a href="./{{ spec.dir }}">{{ spec.title }}</a>
@@ -71,6 +67,5 @@
       {% endfor %}
     </ul>
   </li>
-  {% endif %}
   {% endfor %}
 </ul>