add some comments to the template

fslaborg · Mar 7, 2023 · 9e53dca · 9e53dca
1 parent 56a7d4b
commit 9e53dca
Show file tree

Hide file tree

Showing 5 changed files with 41 additions and 26 deletions.
diff --git a/client/generators/layout.fsx b/client/generators/layout.fsx
@@ -8,36 +8,16 @@
 open Html
 open FsLab.Fornax
 
-let injectWebsocketCode (webpage:string) =
-    let websocketScript =
-        """
-        <script type="text/javascript">
-          var wsUri = "ws://localhost:8080/websocket";
-      function init()
-      {
-        websocket = new WebSocket(wsUri);
-        websocket.onclose = function(evt) { onClose(evt) };
-      }
-      function onClose(evt)
-      {
-        console.log('closing');
-        websocket.close();
-        document.location.reload();
-      }
-      window.addEventListener("load", init, false);
-      </script>
-        """
-    let head = "<head>"
-    let index = webpage.IndexOf head
-    webpage.Insert ( (index + head.Length + 1),websocketScript)
+// Can be used to set the active item color in the navbar to the same color as the hero to get a bookmark effect
 let getBgColorForActiveItem (siteTitle:string) =
     match siteTitle with
     | "Home" -> "is-active-link-magenta"
-    | "Data science packages" -> "is-active-link-lightmagenta"
-    | "Tutorials and Blogposts" -> "is-active-link-darkmagenta"
     | _ -> siteTitle
 
 
+/// The main html skeleton generation happens here.
+/// This function embeds `bodyCnt` into the template's html layout.
+/// Use `active` to control the color of the active menu entry.
 let layout (ctx : SiteContents) active bodyCnt =
     let pages = ctx.TryGetValues<Pageloader.Page> () |> Option.defaultValue Seq.empty
     let siteInfo = ctx.TryGetValue<Globalloader.SiteInfo> ()
@@ -78,5 +58,5 @@ let render (ctx : SiteContents) cnt =
   cnt
   |> HtmlElement.ToString
 #if WATCH
-  |> injectWebsocketCode 
+  |> Globals.injectWebsocketCode 
 #endif
diff --git a/client/generators/staticfile.fsx b/client/generators/staticfile.fsx
@@ -2,6 +2,7 @@
 
 open System.IO
 
+// Static files are served as-is
 let generate (ctx : SiteContents) (projectRoot: string) (page: string) =
     let inputPath = Path.Combine(projectRoot, page)
     File.ReadAllBytes inputPath  
diff --git a/client/globals.fsx b/client/globals.fsx
@@ -1,5 +1,9 @@
+// This file contains functions that can be used everywhere.
+// it should be loaded as the first scriptg in a new loader or generator.
+
 #r "nuget: FsLab.Fornax, 0.0.0"
 
+// fix urls when deployed to base url (e.g. on gh pages via subdomain)
 #if WATCH
 let urlPrefix = 
   ""
@@ -8,4 +12,29 @@ let urlPrefix =
   "{{BASE_URL}}"
 #endif
 
-let prefixUrl url = sprintf "%s/%s" urlPrefix url
+/// returns a fixed urlby prefixing `urlPrefix`
+let prefixUrl url = sprintf "%s/%s" urlPrefix url
+
+/// injects websocket code necessary for hot reload on local preview via `dotnet fornax watch`
+let injectWebsocketCode (webpage:string) =
+    let websocketScript =
+        """
+        <script type="text/javascript">
+          var wsUri = "ws://localhost:8080/websocket";
+      function init()
+      {
+        websocket = new WebSocket(wsUri);
+        websocket.onclose = function(evt) { onClose(evt) };
+      }
+      function onClose(evt)
+      {
+        console.log('closing');
+        websocket.close();
+        document.location.reload();
+      }
+      window.addEventListener("load", init, false);
+      </script>
+        """
+    let head = "<head>"
+    let index = webpage.IndexOf head
+    webpage.Insert ( (index + head.Length + 1),websocketScript)
diff --git a/client/loaders/globalloader.fsx b/client/loaders/globalloader.fsx
@@ -1,5 +1,6 @@
 #r "../_lib/Fornax.Core.dll"
 
+/// Contains gloabl metadata
 type SiteInfo = {
     title: string
     description: string

diff --git a/client/loaders/pageloader.fsx b/client/loaders/pageloader.fsx
@@ -1,11 +1,15 @@
+#load "../globals.fsx"
 #r "../_lib/Fornax.Core.dll"
 
+/// Contains page metadata
 type Page = {
     title: string
     link: string
 }
 
 let loader (projectRoot: string) (siteContent: SiteContents) =
+
+    // currently, only the Home page (index.fsx) is there
     siteContent.Add({title = "Home"; link = "/"})
 
     siteContent