Markdown Page Functionality

.dockerignore

@@ -0,0 +1,2 @@
+apsim-docs-html
+apsim-docs-md

.gitignore

@@ -134,3 +134,5 @@ _NCrunch*
 
 # Specific ignores
 *.html
+apsim-docs-md
+apsim-docs-html

APSIM.Docs.csproj

@@ -2,6 +2,7 @@
 
   <ItemGroup>
     <PackageReference Include="Blazor.Bootstrap" Version="3.2.0" />
+    <PackageReference Include="Markdig" Version="1.3.2" />
   </ItemGroup>
 
   <PropertyGroup>

Components/Custom/DocLink.razor

@@ -6,7 +6,7 @@
 @inject NavigationManager NavigationManager
 
 
-@namespace Components.Custom
+@namespace APSIM.Docs.Components.Custom
 
 <div class="col-xl-3 col-lg-3 col-md-6 col-sm-12 g-2 d-flex">
     <div class="card card-hover-shadow w-100">

Components/Layout/DocSectionLinks.razor

@@ -0,0 +1,75 @@
+@using APSIM.Docs.Components.Custom
+@using APSIM.Docs.Services
+@inject IDocsService DocsService
+
+@namespace APSIM.Docs.Components.Layout
+
+@if (entries.Count == 0)
+{
+    <p>No documentation entries were found in this section.</p>
+}
+else
+{
+    <div class="container">
+        <div class="row">
+            @foreach (var entry in entries)
+            {
+                <DocLink
+                    DocDisplayName="@entry.Title"
+                    DocModelName="@entry.Title"
+                    DocDescript="@entry.Description"
+                    DocLinkHref="@entry.Href" />
+            }
+        </div>
+    </div>
+}
+
+@code {
+    private readonly List<SectionLinkEntry> entries = [];
+
+    [Parameter]
+    public string? SectionSlug { get; set; }
+
+    [Parameter]
+    public bool IncludeIndexPage { get; set; }
+
+    protected override void OnParametersSet()
+    {
+        entries.Clear();
+
+        var sectionNode = string.IsNullOrWhiteSpace(SectionSlug)
+            ? DocsService.GetTree()
+            : DocsService.TryGetDirectory(SectionSlug);
+
+        if (sectionNode is null)
+        {
+            return;
+        }
+
+        if (IncludeIndexPage && sectionNode.IndexPage is not null)
+        {
+            entries.Add(new SectionLinkEntry(
+                sectionNode.IndexPage.Title,
+                "Overview for this section.",
+                $"/docs/{sectionNode.IndexPage.SlugPath}"));
+        }
+
+        foreach (var childDirectory in sectionNode.Directories.OrderBy(directory => directory.Name, StringComparer.OrdinalIgnoreCase))
+        {
+            entries.Add(new SectionLinkEntry(
+                childDirectory.Name,
+                "Click to see more",
+                $"/docs/{childDirectory.SlugPath}"));
+        }
+
+        foreach (var page in sectionNode.Pages.OrderBy(page => page.Title, StringComparer.OrdinalIgnoreCase))
+        {
+            entries.Add(new SectionLinkEntry(
+                page.Title,
+                page.Summary ?? "Open documentation page.",
+                $"/docs/{page.SlugPath}"));
+        }
+    }
+
+    private sealed record SectionLinkEntry(string Title, string Description, string Href);
+}

Components/Layout/HtmlSectionLinks.razor

@@ -0,0 +1,50 @@
+@using APSIM.Docs.Components.Custom
+@using APSIM.Docs.Services
+@inject IHtmlDocsService HtmlDocsService
+
+@namespace APSIM.Docs.Components.Layout
+
+@if (section is null)
+{
+    <p>No documentation entries were found in this section.</p>
+}
+else
+{
+    <div class="container">
+        <div class="row">
+            @foreach (var htmlPage in section.Pages)
+            {
+                <DocLink
+                    DocDisplayName="@htmlPage.DisplayName"
+                    DocModelName="@htmlPage.DisplayName"
+                    DocDescript="Open HTML documentation page."
+                    DocLinkHref="@BuildHref(htmlPage)" />
+            }
+        </div>
+    </div>
+}
+
+@code {
+    private HtmlDocSection? section;
+
+    [Parameter]
+    public string? SectionSlug { get; set; }
+
+    [Parameter]
+    public string? LinkBaseHref { get; set; }
+
+    protected override void OnParametersSet()
+    {
+        section = HtmlDocsService.TryGetSection(SectionSlug);
+    }
+
+    private string BuildHref(HtmlDocPage page)
+    {
+        if (!string.IsNullOrWhiteSpace(LinkBaseHref))
+        {
+            return $"{LinkBaseHref!.TrimEnd('/')}/{page.FileStem}";
+        }
+
+        return $"/html/{page.SectionSlug}/{page.FileStem}";
+    }
+}

Components/Layout/NavMenu.razor

@@ -1,4 +1,8 @@
-<div class="top-row ps-3 mb-5 navbar navbar-dark">
+@using APSIM.Docs.Services
+@inject IHtmlDocsService HtmlDocsService
+@inject IDocsService DocsService
+
+<div class="top-row ps-3 mb-5 navbar navbar-dark">
     <div class="container-fluid">      
         <a class="navbar-brand" href="/">
             <img src="APSIM_transparent-154x100.png" />
@@ -10,31 +14,54 @@
 
 <div class="nav-scrollable" onclick="document.querySelector('.navbar-toggler').click()">
     <nav class="flex-column">
-        <div class="nav-item px-3">
-            <NavLink class="nav-link" href="" Match="NavLinkMatch.All">
-                <span class="" aria-hidden="true">
-                    <Icon Name="IconName.ClipboardCheckFill" Size="IconSize.x2" class="me-3 ms-1"></Icon>
-                </span> Validation
-            </NavLink>
-        </div>
-
-        <div class="nav-item px-3">
-            <NavLink class="nav-link" href="tutorials">
-                <span class="" aria-hidden="true">
-                    <Icon Name="IconName.BookFill" Size="IconSize.x2"class="me-3 ms-1"></Icon>
-                </span> Tutorials
-            </NavLink>
-        </div>
-
-        <div class="nav-item px-3">
-            <NavLink class="nav-link" href="models">
-                <span class="" aria-hidden="true">
-                    <Icon Name="IconName.FileCodeFill" Size="IconSize.x2" class="me-3 ms-1"></Icon>
-                </span> Models
-            </NavLink>
-        </div>
+        <div class="nav-item px-3 text-white-50 small mt-2">APSIM Generated Docs</div>
+        @foreach (var item in HtmlMenuItems)
+        {
+            <div class="nav-item px-3">
+                <NavLink class="nav-link" href="@item.Href" Match="NavLinkMatch.Prefix">
+                    <span class="" aria-hidden="true">
+                        <Icon Name="@item.IconName" Size="IconSize.x2" class="me-3 ms-1"></Icon>
+                    </span> @item.Title
+                </NavLink>
+            </div>
+        }
+
+        <div class="nav-item px-3 text-white-50 small mt-3">APSIM User Docs</div>
+        @foreach (var item in MarkdownMenuItems)
+        {
+            <div class="nav-item px-3">
+                <NavLink class="nav-link" href="@item.Href" Match="NavLinkMatch.Prefix">
+                    <span class="" aria-hidden="true">
+                        <Icon Name="@item.IconName" Size="IconSize.x2" class="me-3 ms-1"></Icon>
+                    </span> @item.Title
+                </NavLink>
+            </div>
+        }
     </nav>
 </div>
 
+@code {
+    private IEnumerable<NavMenuItem> HtmlMenuItems => HtmlDocsService
+        .GetSections()
+        .Select(section => new NavMenuItem(section.Name, GetHtmlSectionHref(section.Slug), IconName.FileCodeFill));
+
+    private IEnumerable<NavMenuItem> MarkdownMenuItems => DocsService
+        .GetTopLevelSections()
+        .Select(section => new NavMenuItem(section.Name, $"/docs/{section.SlugPath}", IconName.JournalText));
+
+    private static string GetHtmlSectionHref(string sectionSlug)
+    {
+        return sectionSlug switch
+        {
+            "models" => "/models",
+            "tutorials" => "/tutorials",
+            "validation" => "/validation",
+            _ => $"/html/{sectionSlug}"
+        };
+    }
+
+    private sealed record NavMenuItem(string Title, string Href, IconName IconName);
+}
+