add ToC, fix broken links (#449)

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: mvadari

scripts/assets/style.css

@@ -420,7 +420,8 @@ main {
 .document-content h3,
 .document-content h4,
 .document-content h5,
-.document-content h6 {
+.document-content h6,
+.document-content .toctitle {
   margin-top: 32px;
   margin-bottom: 16px;
   color: var(--text-color);
@@ -433,6 +434,11 @@ main {
   font-size: 32px;
 }
 
+.document-content .toctitle {
+  padding-bottom: 16px;
+  font-size: 32px;
+}
+
 .document-content h1 .headerlink,
 .document-content h2 .headerlink,
 .document-content h3 .headerlink,

scripts/build_site.py

@@ -7,6 +7,7 @@
 import os
 import shutil
 from pathlib import Path
+import re
 
 import markdown
 from jinja2 import Environment, FileSystemLoader
@@ -17,11 +18,16 @@
 
 def convert_markdown_to_html(content: str) -> str:
     """Convert markdown content to HTML."""
+    # Insert a TOC marker after the first metadata block, unless one already exists.
+    if "[TOC]" not in content:
+        content = re.sub(r"</pre>", "</pre>\n\n[TOC]\n\n", content, count=1)
+    content = re.sub(r"\.\./(XLS-[0-9A-Za-z-]+)/README\.md", r"./\1.html", content)
+
     md = markdown.Markdown(
         extensions=["extra", "codehilite", "toc", "tables"],
         extension_configs={
             "codehilite": {"css_class": "highlight"},
-            "toc": {"permalink": True},
+            "toc": {"permalink": True, "baselevel": 2, "toc_depth": 3, "title": "Table of Contents"},
         },
     )
     return md.convert(content)