WIP conversion to JustTheDocs formatting.

Author: rspeele

Gemfile

@@ -0,0 +1,18 @@
+# Gem manifest for the GitHub-Pages Jekyll build of the Rezoom.SQL docs.
+#
+# The github-pages metagem pins every Jekyll dependency to the exact
+# version GitHub's Pages builder runs in production, so what you see
+# locally with `bundle exec jekyll serve` matches what gets published.
+#
+# Just-the-Docs is consumed as a remote theme (configured in _config.yml),
+# not as a gem dependency here — jekyll-remote-theme is included in
+# github-pages and fetches it at build time.
+
+source "https://rubygems.org"
+
+gem "github-pages", group: :jekyll_plugins
+
+# Local-preview prerequisites. Harmless on the GitHub builder; needed on
+# Windows / macOS dev machines.
+gem "wdm", ">= 0.1.0" if Gem.win_platform?
+gem "tzinfo-data", platforms: [:mingw, :x64_mingw, :mswin, :jruby]

README.md

@@ -1,3 +1,8 @@
+---
+title: About
+nav_order: 0
+---
+
 <!-- nav-top -->
 **Documentation:** [Tutorial](doc/Tutorial/README.md) | [Using Rezoom](doc/Rezoom/README.md) | [Configuration](doc/Configuration/README.md) | [Language](doc/Language/README.md) | [API](doc/API/README.md)
 <!-- /nav-top -->

_config.yml

@@ -0,0 +1,69 @@
+# Jekyll + Just-the-Docs configuration. Pages this site builds are
+# every .md file in the repo NOT excluded below, with frontmatter
+# generated by build/regen-doc-nav.ps1 from SUMMARY.md.
+
+title: Rezoom.SQL
+description: F# type provider for compile-time-checked SQL queries with built-in async batching.
+# TODO: replace with the real GH Pages URL once Pages is configured for
+# the preview branch (Settings -> Pages -> source). Format is typically
+# https://<user-or-org>.github.io/<repo>
+url: https://example.github.io
+baseurl: /Rezoom.SQL
+
+# Just-the-Docs is consumed as a remote theme so the site builds on the
+# stock GitHub-Pages Jekyll runner with no Actions workflow needed. The
+# github-pages metagem (declared in Gemfile) supplies jekyll-remote-theme.
+remote_theme: just-the-docs/just-the-docs
+
+plugins:
+  - jekyll-remote-theme
+
+# --- Theme options -------------------------------------------------------
+
+# Built-in client-side search index built at site-build time.
+search_enabled: true
+search:
+  heading_level: 3
+  previews: 2
+  preview_words_before: 3
+  preview_words_after: 3
+  tokenizer_separator: /[\s/]+/
+
+# Auto-generate anchor links on each heading.
+heading_anchors: true
+
+color_scheme: light
+
+# Top-right links rendered in the theme header. Edit the URL to match
+# wherever this repo actually lives.
+aux_links:
+  "View on GitHub":
+    - "https://github.com/rspeele/Rezoom.SQL"
+aux_links_new_tab: true
+
+# Theme-rendered footer text (per-page).
+footer_content: 'Rezoom.SQL documentation. <a href="https://github.com/rspeele/Rezoom.SQL">Source on GitHub</a>.'
+
+# --- Build excludes ------------------------------------------------------
+# Jekyll otherwise tries to render every file in the repo. Keep this list
+# tight: only docs (.md files referenced from SUMMARY.md) should reach the
+# generated site.
+
+exclude:
+  - Gemfile
+  - Gemfile.lock
+  - vendor/
+  - .bundle/
+  - build/
+  - src/
+  - tests/
+  - test-tp-users.ps1
+  - LICENSE*
+  - CONTRIBUTING*
+  - "*.sln"
+  - "*.fsproj"
+  - "*.csproj"
+  - "*.fs"
+  - "*.cs"
+  - "*.gv"
+  - SUMMARY.md

build/regen-doc-nav.ps1

@@ -1,24 +1,32 @@
 #requires -Version 5
 <#
 .SYNOPSIS
-    Regenerate breadcrumb + prev/next navigation blocks in every doc page.
+    Regenerate breadcrumb + prev/next navigation blocks in every doc page,
+    and emit Just-the-Docs YAML frontmatter for the gh-pages-built sidebar.
 
 .DESCRIPTION
     Parses SUMMARY.md at the repo root, walks its tree depth-first to build a
-    linear reading order, and rewrites a marker-fenced nav block at the top
-    and bottom of every .md file referenced.
+    linear reading order, and rewrites three sections of every .md file
+    referenced:
 
-    The top block is breadcrumbs (Home > Section > Page) followed by a
-    prev / next bar. The bottom block is a horizontal rule and a prev / next
-    bar. Both are wrapped in HTML comment markers (`<!-- nav-top -->` /
-    `<!-- nav-bottom -->`) so the script can rerun and rewrite cleanly when
-    SUMMARY.md changes.
+    1. YAML frontmatter at the very top of the file driving the
+       Just-the-Docs sidebar nav (`title`, `parent`, `grand_parent`,
+       `nav_order`, `has_children`).
+    2. A marker-fenced nav block (`<!-- nav-top -->`) below the frontmatter
+       with breadcrumbs (Home > Section > Page) and a prev/next bar.
+    3. A marker-fenced bottom nav block (`<!-- nav-bottom -->`) with a
+       horizontal rule and another prev/next bar.
+
+    All three are idempotent: rerunning the script after SUMMARY.md changes
+    cleanly strips and rewrites without accumulating cruft.
 
     Also strips the legacy "(this page is part of...)" preamble lines from
     Tutorial pages, since the new breadcrumb supersedes them.
 
 .NOTES
     Re-run after editing SUMMARY.md (adding pages, reordering, renaming).
+    The frontmatter is consumed by Jekyll + just-the-docs; the marker-fenced
+    nav blocks serve readers viewing the markdown raw on github.com.
 #>
 [CmdletBinding()]
 param()
@@ -80,6 +88,38 @@ for ($i = 0; $i -lt $entries.Count; $i++) {
     $entries[$i] | Add-Member -NotePropertyName Next -NotePropertyValue $next
 }
 
+# ---- Compute SiblingOrder + HasChildren (for Just-the-Docs frontmatter) -
+
+# SiblingOrder: 1-based position among entries sharing the same immediate
+# parent. Top-level entries (depth 0) are siblings of each other under a
+# synthetic '<root>' key.
+$siblingCounter = @{}
+foreach ($e in $entries) {
+    $parentKey =
+        if ($e.Parents.Count -gt 0) {
+            $e.Parents[$e.Parents.Count - 1].RelPath
+        } else { '<root>' }
+    if (-not $siblingCounter.ContainsKey($parentKey)) {
+        $siblingCounter[$parentKey] = 0
+    }
+    $siblingCounter[$parentKey]++
+    $e | Add-Member -NotePropertyName SiblingOrder -NotePropertyValue $siblingCounter[$parentKey]
+}
+
+# HasChildren: true if any other entry's immediate parent is this entry.
+# Just-the-Docs uses this to expand the page as a parent node in the sidebar.
+foreach ($e in $entries) {
+    $hasChildren = $false
+    foreach ($other in $entries) {
+        if ($other.Parents.Count -gt 0 -and
+            $other.Parents[$other.Parents.Count - 1].RelPath -eq $e.RelPath) {
+            $hasChildren = $true
+            break
+        }
+    }
+    $e | Add-Member -NotePropertyName HasChildren -NotePropertyValue $hasChildren
+}
+
 # ---- Helpers ----
 
 function Get-Rel($fromFile, $toFile) {
@@ -116,6 +156,34 @@ function Build-Breadcrumb($entry) {
     return ($parts -join ' &gt; ')
 }
 
+function Build-Frontmatter($entry, $isRoot) {
+    # Just-the-Docs YAML frontmatter. Drives the sidebar nav structure.
+    # On rerun, the strip regex below removes any existing frontmatter
+    # block at the top of the file and this writes a fresh one.
+    if ($isRoot) {
+        # The root README is the site landing page. Just-the-Docs treats
+        # it as the home; nav_order: 0 keeps it first if it ever ends up
+        # rendered in the sidebar.
+        return "---`ntitle: $($entry.Title)`nnav_order: 0`n---"
+    }
+    $lines = @("title: $($entry.Title)")
+    if ($entry.Parents.Count -ge 1) {
+        $immediate = $entry.Parents[$entry.Parents.Count - 1]
+        $lines += "parent: $($immediate.Title)"
+    }
+    if ($entry.Parents.Count -ge 2) {
+        # Just-the-Docs requires grand_parent for any page nested three
+        # levels deep so the sidebar knows where to slot it.
+        $grand = $entry.Parents[0]
+        $lines += "grand_parent: $($grand.Title)"
+    }
+    $lines += "nav_order: $($entry.SiblingOrder)"
+    if ($entry.HasChildren) {
+        $lines += "has_children: true"
+    }
+    return "---`n" + ($lines -join "`n") + "`n---"
+}
+
 function Build-PrevNext($entry) {
     $prevPart =
         if ($entry.Prev) {
@@ -157,6 +225,15 @@ $legacyPreamble = "^\(this page is part of \[[^\]]+\]\([^)]+\)\)\s*\r?\n"
 # the bottom-regex started consuming them. Allows blank lines between adjacent
 # orphans (which is exactly the pattern previous buggy runs produced).
 $trailingOrphanSep = "(?:\r?\n\s*---[ \t]*)+\s*$"
+# Existing YAML frontmatter at the very top of the file. The keyed-content
+# requirement (`(?:[a-zA-Z_]\w*: [^\r\n]*\r?\n)+` between the delimiters)
+# keeps the regex from misfiring on a file that genuinely opens with a bare
+# `---` horizontal rule and no frontmatter, AND uses [^\r\n]* (not .*) so the
+# value portion can't span newlines — important because on the second run
+# the file does have frontmatter, and a greedy .* would otherwise extend
+# down to the next `---` separator and consume the entire body. Trailing
+# blank lines are also consumed so successive runs don't drift the body.
+$frontmatterRegex = "\A---\r?\n(?:[a-zA-Z_]\w*: [^\r\n]*\r?\n)+---\r?\n\r?\n?"
 
 $touched = 0
 foreach ($e in $entries) {
@@ -167,6 +244,10 @@ foreach ($e in $entries) {
     $path = $e.AbsPath.Path
     $body = [System.IO.File]::ReadAllText($path)
 
+    # Strip existing frontmatter at the very top of the file FIRST so the
+    # nav-top strip below sees the actual `<!-- nav-top -->` marker at the
+    # head of the body.
+    $body = [regex]::Replace($body, $frontmatterRegex, '')
     # Strip existing nav blocks (anywhere in the file, idempotent).
     $body = [regex]::Replace($body, $navTopRegex, '')
     $body = [regex]::Replace($body, $navBottomRegex, '')
@@ -199,7 +280,8 @@ foreach ($e in $entries) {
     # Trim leading blank lines that may have been left by the strip, and
     # trailing whitespace, so the output is tidy.
     $body = $body.TrimStart("`r","`n"," ","`t").TrimEnd()
-    $newBody = $topBlock + $body + $bottomBlock + "`n"
+    $frontmatter = Build-Frontmatter $e ($e -eq $rootEntry)
+    $newBody = "$frontmatter`n`n$topBlock$body$bottomBlock`n"
 
     [System.IO.File]::WriteAllText($path, $newBody, [System.Text.UTF8Encoding]::new($false))
     $touched++

doc/API/README.md

@@ -1,3 +1,9 @@
+---
+title: API
+nav_order: 6
+has_children: true
+---
+
 <!-- nav-top -->
 [Home](../../README.md) &gt; API
 

doc/API/RezoomSQL.md

@@ -1,3 +1,9 @@
+---
+title: Rezoom.SQL
+parent: API
+nav_order: 1
+---
+
 <!-- nav-top -->
 [Home](../../README.md) &gt; [API](README.md) &gt; Rezoom.SQL
 

doc/API/RezoomSQLAsynchronous.md

@@ -1,3 +1,9 @@
+---
+title: Rezoom.SQL.Asynchronous
+parent: API
+nav_order: 3
+---
+
 <!-- nav-top -->
 [Home](../../README.md) &gt; [API](README.md) &gt; Rezoom.SQL.Asynchronous
 

doc/API/RezoomSQLMigrations.md

@@ -1,3 +1,9 @@
+---
+title: Rezoom.SQL.Migrations
+parent: API
+nav_order: 5
+---
+
 <!-- nav-top -->
 [Home](../../README.md) &gt; [API](README.md) &gt; Rezoom.SQL.Migrations
 

doc/API/RezoomSQLPlans.md

@@ -1,3 +1,9 @@
+---
+title: Rezoom.SQL.Plans
+parent: API
+nav_order: 4
+---
+
 <!-- nav-top -->
 [Home](../../README.md) &gt; [API](README.md) &gt; Rezoom.SQL.Plans
 

doc/API/RezoomSQLSynchronous.md

@@ -1,3 +1,9 @@
+---
+title: Rezoom.SQL.Synchronous
+parent: API
+nav_order: 2
+---
+
 <!-- nav-top -->
 [Home](../../README.md) &gt; [API](README.md) &gt; Rezoom.SQL.Synchronous