overview: rebuild the rendering flow so that we can use markdown strings

overview/default.nix

@@ -18,6 +18,7 @@ let
     substring
     toJSON
     toString
+    replaceStrings
     ;
 
   join = concatStringsSep;
@@ -75,6 +76,11 @@ let
     packages = project: attrValues project.packages;
   };
 
+  # This doesn't actually produce a HTML string but a Jinja2 template string
+  # literal, that is then replaced by it's HTML translation at the last build
+  # step.
+  markdownToHtml = markdown: "{{ markdown_to_html(${toJSON markdown}) }}";
+
   render = {
     options = rec {
       one =
@@ -91,7 +97,7 @@ let
           </dt>
           <dd class="option-body">
             <div class="option-description">
-            ${option.description}
+            ${markdownToHtml option.description}
             </div>
             <dl>
               <dt>Type:</dt>
@@ -289,10 +295,10 @@ let
       </html>
     '';
 
-  # Ensure that directories exist and that HTML is complete and works as a standalone file
+  # Ensure that directories exist and render the jinja2 template that we composed with Nix so far
   writeHtmlCommand = path: htmlFile: ''
     mkdir -p "$out/$(dirname '${path}')"
-    ln -s '${htmlFile}' "$out/${path}"
+    python3 ${./render-template.py} '${htmlFile}' "$out/${path}"
   '';
 
   fonts =
@@ -314,6 +320,12 @@ pkgs.runCommand "overview"
     nativeBuildInputs = with pkgs; [
       jq
       validator-nu
+      (python3.withPackages (
+        ps: with ps; [
+          jinja2
+          markdown-it-py
+        ]
+      ))
     ];
   }
   (

overview/render-template.py

@@ -0,0 +1,16 @@
+import sys
+from jinja2 import Template
+from markdown_it import MarkdownIt
+
+jinja2_template_file = sys.argv[1]
+output_file = sys.argv[2]
+
+md = MarkdownIt("commonmark")
+
+with open(jinja2_template_file) as file:
+  jinja2_template = Template(file.read())
+
+rendered = jinja2_template.render(markdown_to_html=md.render)
+
+with open(output_file, "w") as file:
+  file.write(rendered)